前后端联调对接规范 | OneYoung’s Blog

前端偏向于视觉交互，后端偏向于数据逻辑，因此在联调过程中，前后端研发看待需求的角度是不同的。

但前后端的开发，都必须基于项目需求。

由于沟通成本和人员理解不一致甚至接口不满足需求实现的影响，前后端联调的效率也是目前项目提测的瓶颈。

另外，在某种程度上，接口质量是前端代码质量的瓶颈。接口的质量，直接影响前端代码中是否需要做大量的容错处理。

因此，前后端联调的过程中，需要有一套规范，来保证前后端的开发效率。

# 1.代码风格

变量名尽量使用名词，方法名尽量使用动词，英文单词使用驼峰命名法。
GET 请求使用 url 中的 querystring，无 Content-Type。
POST 请求的 Content-Type 使用 application/json，不推荐使用 application/x-www-form-urlencoded。
FILE 文件上传 Content-Type 使用 multipart/form-data。

Click me

# 2.接口定义

接口定义必须提供 swagger 等文档。
接口地址是以网关地址为参照。

// Good ✅
http://sit8.cbi-ls-gateway.sitcbi.com/cbi-ls-customer/swagger#/

// Bad ❌
http://dev1.pay-aml-boss.devcbi.com/swagger#/

1
2
3
4
5

这样的话，就能直接使用 /cbi-ls-customer 代理到 http://sit8.cbi-ls-gateway.sitcbi.com。

TIP

跨域处理，联调阶段采用 webpack-dev-server 作本地代理，部署阶段均采用 nginx 反向代理。

接口需要清楚定义入参和出参，且划分详细。没有多余字段。

Click me

接口文档针对入参和出参的每个字段，都要有对应的中文说明。且中文说明应与原型字段名称保持一致。

Click me

出参需要明确定义默认值。对象类型的返回空对象 {}, 数组类型的返回空数组 []，字符串类型的返回空字符串 ""， Number 和Boolean 类型的返回 null。

// Good ✅
{
  "code": 0,
  "data": [],
  "msg": "success"
}

// Bad ❌
{
  "code": 0,
  "data": null,
  "msg": "success"
}

1
2
3
4
5
6
7
8
9
10
11
12
13

# 3.业务对接

前端专注客户交互，后端专注业务数据。

业务状态、国家列表、国码列表等枚举在大多数场景下都应该提供接口。前端不在项目写死固定值。
查询一类的接口，如果涉及到枚举，接口要返回对应字段，前端不做映射处理。譬如：

{
  "cstNo": "...",
  "amount": "1000",
  "status": "OPENING",
  "statusName": "开通中",
  "statusNameEn": "Opening"
}

1
2
3
4
5
6
7

查询一类的接口，如果查全部数据，推荐传递空字符串，而非删除入参。譬如：

// Good ✅
{
  startDate: '2023-05-01',
  endDate: '2023-05-31'
  status: '',
  pageNo: 1,
  pageSize: 10
}

// Bad ❌
{
  startDate: '2023-05-01',
  endDate: '2023-05-31'
  pageNo: 1,
  pageSize: 10
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

对于有中英文切换等需求，接口要支持中英文。

TIP

目前项目会以请求头中的 accept-language 为准，返回对应语言的 error 报错信息或 info 提示信息。
枚举一类的接口，同时返回 showName 和 showNameEn。
查询一类的接口，也要返回对应的 name 和 nameEn。

对于大数字(如 Java 的 long 类型)，返回给前端时需要设置为字符串类型, 防止 JavaScript 发生溢出。
如果数字金额需要保留两位小数，那么此时推荐以字符串形式返回给前端。因为浏览器会吞掉部分小数位。

// Good ✅
'144.00' => '144.00'

// Bad ❌
144.00 => 144

1
2
3
4
5

接口要进行自测，联调时，要保证接口根据入参调用时，功能正常，且出参与文档定义一致。避免出现首次调用即系统繁忙的场面。
接口丢失或缺少，说明对于业务需求的理解有歧义。因此，必要的话，在评审需求完毕之后，后端同学可以主动跟前端同学碰一下接口。
接口入参和出参的更改，要体现到文档上。口头传达，只是快捷渠道。前后端的对接始终以文档为准。
确认好联调时间后，提前部署下所有环境。