环球通REST接口开发规范

Version : 1.0

Date : 2022-5-6

Version	Remark
1.0	初始化

0. 目的

分工清晰、职责明确
每个开发人员更加专注于自己的工作
系统边界清晰，封装更合理规范
前后端的debug更加容易

1. 交互方

前端
- H5
- 小程序
- MP/OP
- Android
Mobile Api
后端
- Java

2. 规则描述

总则

基于HTTP协议，符合Http/1.1标准（可能很快就需要考虑Http/2.0标准），保证各方对接口理解的一致性。主要针对输入的method/headers，以及输出的status code，尽量的满足RFC一致性。
迁移原则
- 自发布之日起，新接口需按照本规范来进行开发
- 老接口保持原样，如需变更，必须同时通知到上下游，一起评估修改影响及可行性

URI 规范

服务提供方主要是根据每个项目提供服务，所有根目录使用对应的服务名称命名,形如：http://host/service/controller/action/{id} 区分各个项目。
service 代表当前应用名称名称，跟项目工程名保持一致，例如：https://wxa.xxx.cn/room-mobile-api/order/get_detail
controller 代表当前业务逻辑控制器名称，例如：order、user
用户c端H5的接口path必须是/front/**
商户的接口path必须是/mp/**（商户平台/商户小程序等商户端接口）
运营后台使用的接口必须是/op/**
三方接口调用必须是/open/**
三方接口如为公开接口/public/**
action 代表当前接口对应的操作，例如：get、submit
仅允许一个int型变量出现在path中
url 中仅允许小写字母、数字、下划线、中横线（仅允许出现在controller中）

Method 规范

GET: 获取某个资源，GET操作应该是幂等（idempotence）的，且无副作用。
POST: 创建或修改一个资源。
DELETE：删除某个资源。DELETE操作有副作用，但也是幂等的。

如需增加自定义 Header，须经过技术委员会备案
目前仅允许如下自定义 Header
- 自定义header：language，接口多语言信息
- 自定义header：trace-id，Request 级别唯一id，用于链路分析

参数规范

允许以下几种类型的参数：

URL QueryString Parameter
- 例如：/service/module/action?a=xx&b=xx
- 只允许在GET方法中出现
URL Path Parameter
- 例如：/service/module/delete_by_id/{id}
- 只允许主键类型参数出现在路径变量中
Request Body JSON Parameter
- 复杂参数应该包装成对象放到 body 中
- Content-Type : application/json
File Parameter
- Content-Type : multipart/form-data

Http Status Code 规范

200：代表业务系统收到请求并正常响应业务请求（但业务逻辑上的异常情况，应该通过响应体里的code来进行描述）
5XX：由框架或网关统一返回，业务代码不应该设置5XX状态码
3XX：一般不允许出现在业务接口
4XX
- 由框架或容器返回，例如找不到资源返回404
- Header 验证不合法，可返回400，例如：依赖的某个私有头缺失
- 如果鉴权失败，可返回403

数据结构

Java

{
  "code": "0",
  "data": null,
  "message": "productLine:不能为空;",
  "success": false,
  "timestamp": "2023-05-18 10:11:38",
  "traceId": "op-api-gatewaybb6e534a-2c99-401d-b1a8-a1d85b368b6c"
}

关于 code 码的说明：

等于0，代表正常响应
大于0，代表业务异常
- 根据接口重要程度，接入千里眼监控报警
小于0，代表系统异常
- 应该记录详细异常日志，并接入千里眼监控报警

分页数据

分页入参基类Java版：

public abstract class BasePage implements Serializable {


    private static final long serialVersionUID = 2400016365760414364L;

    /**
     * 页码,默认pageNo=1
     */
    private Integer pageNo;
    /**
     * 页容量,默认pageSize=20
     */
    private Integer pageSize;

    ...
}

需要分页时，可以用实体类继承该基类。

分页响应类：

public class ListResult<T> {

    /**
     * 总记录数
     */

    private int total;

    /**
     * 分页数据集合
     */

    private List<T> list = new ArrayList();

    ...
}

分页数据 Json 结构为：


{"list": [],"total": 0}

数据类型

金融类

对于金融类数据字段，统一使用“分”作为单位，例如某产品单价599元，则后端接口数据如下：

{
  "productPrice" : 59900
}

沟通协作

任何一个项目开始前，前后端都应该本着接口契约先行的原则进行合作，产品需求说明会之后，前后端开发组织接口契约沟通会，协商具体的接口和结构，该工作由项目整体技术Owner主导，并将结论沉淀成技术文档。

4.2 REST接口开发规范