前后端工作职能界定 #

• 后端专注于数据格式、逻辑的处理，前端只关注数据的呈现及交互。如果涉及到需要前端对后端返回的数据做一层额外的逻辑判断（哪怕是简单的if else），均应该放到后端处理，所有需要呈现或使用的数据，均应由后端处理好，前端直接进行呈现使用。

接口文档 #

• 后端编写和维护接口文档(按照openapi标准，工具选用swagger，保证接口核心数据的完整。核心数据包括：接口地址，名称，入参信息，返回信息，上述参数内容包含数据格式、字段名称、类型、中文注释)，在API变化时更新接口文档，接口的请求参数和返回参数需备注清楚
• 任何形式的接口、数据等变更均应该通知相应的前端开发人员并重新对接
• 对同一实体进行操作的接口应尽量保证在请求参数和返回数据中，数据格式保持一致，尽量避免前端做数据对象转换的动作

Mock数据 #

• 联调过程中，需要数据进行联调效果展示的情况下，后端优先创建真实数据，时间不允许或其他可协调的情况下，可利用 Apifox 等工具的Mock功能进行接口数据的补充。

协议规范 #

• GET：用于从服务器获取资源信息
• POST：用于创建新资源
• PUT：用于完整的替换资源或者创建制定身份的资源
• DELETE：用户删除某个资源

请求头 #

• Authorization: 请求令牌
• Content-Type: application/json 或 application/x-www-form-urlencoded
• X-Request-Id: xxxxxxxxxxxxx (uuid4) 请求ID，用于和后端日志进行关联

响应头 #

• Access-Control-Allow-Origin: *
• Content-Type: application/json 或 application/x-www-form-urlencoded

返回数据 #

• 接口返回的数据字段需全部放在 data 字段里面
• 在提交操作中，如果涉及到下拉框、复选框、单选框等联级选择字段，返回数据除了返回所选数据的 ID 之外，还需要返回该选择项的其他具体信息
• 正常数据格式

{
    "code": 200,
    "data": {},
    "message": "操作成功"
}

• 异常数据格式

{
    "code": 100,
    "data": {
        "detail": "手机号格式不正确"
        
    },
    "message": "系统异常"
}

{
    "code": 0,
    "data": {
        "detail": "服务异常"
        
    },
    "message": "系统异常"
}

• 分页数据格式

{
    "code": 200,
    "data": {
        "data": [],
        "page": 1,
        "pageSize": 10,
        "total": 100
    },
    "message": "操作成功"
}

请求参数 #

• 单一项目中，前后端传输字段需采用驼峰式或下划线命名，二者选其一，格式确定后纳入版本库中描述清楚，所有参与人员进行统一
• GET

// Query String Parameters
get('https://xxx?type=1&state=2')

// 分页参数
get('https://xxx?page=1&size=10&search=test')

• POST、PUT

// 如果 Content-Type = application/json
post({
    url: 'https://xxx',
    data: {
        type: 1,
        state: 2
    }
})

// 如果 Content-Type = application/x-www-form-urlencoded
let formData = new FormData()
formData.append('type', 1)
formData.append('state', 2)
post({
    url: 'https://xxx',
    data: formData
})

• 时间参数

// 统一使用格式化的时间字符串 yyyy-MM-dd HH:mm:ss
get('https://xxx?time=2022-9-1 10:30:10')

code 状态码 #

• 200：请求成功并返回相应数据
• 100：请求成功并返回错误提示
• 401：请求令牌失效需重新验证用户身份
• 403：当前账户无权限访问该资源
• 404：找不到目标资源
• 420：账号异地登录导致当前账号登录状态失效
• 500：服务器异常导致请求失败
• 504：网关超时，服务一直未响应

接口URL规范 #

• https://test.com/api/服务名/版本号/模块名/接口名
• 不能使用大写，用中横线 - 不用下划线 _
• 接口地址需要按照可预测的层级结构来生成，提高可理解性

GET https://test.com/api/v1/test-module/user
POST https://test.com/api/v1/test-module/user/bind

日期、时间字段规范 #

• 所有的日期、时间字段在接口联调过程中，均为 时间戳 格式进行传输
• 页面上需呈现的日期、时间字段，均由前端通过 utils.dateFormat(xxx, 'YYYY-MM-DD HH:mm:ss') 该方法对 时间戳 进行格式化显示