1. 概述※
1.1. 编写目的※
本规范旨在规范集团项目微服务接口定义的一致性，确保集团项目研发风格统一，为项目微服务接口设计提供参考指导，同时也为集团数字化设计中心全方位、全流程、全要素开展集团项目精益化技术管控提供依据。
1.2. 适用范围※
本规范作为微服务接口设计的参考规范，各项目可根据场景需要在本参考规范基础上进行调整及扩展，形成各项目私有接口定义规范。
本规范不适用于应用系统对外暴露的集成服务接口。
1.3. 设计约束※
微服务接口采用RESTful形式。
微服务接口采用Unicode字符集，UTF-8编码方式。
微服务接口请求、响应消息体数据均为JSON格式，文件上传/下载接口为二进制格式。
微服务接口推荐使用Swagger进行展示和说明。
微服务接口方法推荐采用GET或POST请求方式。
微服务接口设计需要考虑网络超时、重复调用等情况下的业务一致性，接口设计须考虑幂等。
同一应用内相同业务对应的参数定义应保持一致。
2. 接口设计规范※
2.1. 接口访问场景※
如上图所示，微服务架构下的接口访问场景主要分A（前端接入网关接口）、B（微服务接口）两类，由微服务网关负责两类报文之间的协议转换。
| 接口访问场景分类 | 描述 |
| A类：微服务网关接口 | 微服务网关暴露给前端微应用的接口 |
| B类：微服务接口 | 各微服务模块提供的服务能力接口 |
2.2. 访问地址约定※
https://<IP>:<port>/<domain>/[route_prefix]/<module>/<method>
接口名称
域标识：可选，构建项目子域的英文名称或简称， 原则上不超过10个字母。
路由前缀：根据项目规范自行约定，通过路由前缀路由到具体微服务，可定义多级，例：采用项目缩写标识+英文名词命名，如人资系统：hr-system/，hr-audit/oper
模块名称：
模块名称使用“名词”命名，名称采用小写英文，多个单词间用中横线“-”分隔，禁止使用汉语拼音。
模块命名支持最多两级目录，均采用名词命名方式，例如：dept/user。
命名参考：机构管理（org）、部门管理（dept）、用户管理（user）、审计日志（audit-log）、业务日志（biz-log）。
接口名称：接口名称使用具有业务含义的“英文动词”方式，全部字母小写，多个单词采用中横线“-”方式分隔，禁止使用汉语拼音。
常用命名参考：
| 中文名 | 英文命名 | 中文名 | 英文命名 |
| 新增 | add | 获取详细 | view |
| 更新 | update | 获取主从 | view-with-xxxx |
| 删除 | delete | 获取全貌 | view-whole |
| 撤销 | invalid | 分页查询 | query |
| 恢复 | recover | 全部查询 | query-all |
| 冻结 | freeze | 支付 | pay |
| 解冻 | unfreeze | 稽核 | audit |
| 提交 | commit | 冲销 | reverse |
| 复核 | check | 回复 | reply |
| 审核 | audit |
版本号：URL路径中版本号v1版本默认省略，后续版本针对实际场景可在微服务、模块、接口层级分别定义。如下为在微服务、模块、接口层级定义的版本号示例(针对大版本变更)：
服务级：
https://[IP:port]/{domain}/xxxx-xxxx/v2/module/method
模块级：
https://[IP:port]/{domain}/xxxx-xxxx/module/v2/method
接口级：
https://[IP:port]/{domain}/xxxx-xxxx/module/method/v2
2.3. 微服务网关接口规范（A类接口）※
微服务网关接口（A类接口），即前端应用层访问微服务网关的接口，推荐采用上图所示的消息结构。
请求报文头：在请求的消息头中定义Client-Header、 token、User-Agent、sign属性，其中Client-Header中定义timestamp、version属性；
响应报文头：在响应的消息头中定义Client-Header、sign属性，Client-Header中定义requestID属性。
防篡改：建议微服务网关通过对sign摘要规则进行验证，确认请求报文是否被篡改。
防重放：建议微服务网关通过共享缓存（超时自动清理），对请求报文中的sign作为请求报文唯一标识进行防重放控制，建议检查服务器时间与请求报文时间戳的时间间隔是否在有效期内，以有效保护后台微服务不被恶意拦截重放。
安全加密：等保三级及以上业务领域，请求及响应报文的消息体建议采用国密加密传输，通信协议建议采用HTTPS加密通道。等保二级应针对敏感数据进行报文加密，根据项目安全要求选择HTTP或HTTPS通讯协议。
2.3.1. 请求报文规范※
请求报文消息头信息：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| Client-Header | 用户信息请求头 | JSON | 用户信息请求头信息，为JSON字符串，由调用方填写 | 是 | {"timestamp":"1626768677928","version":"1.3"} |
| token | token | String | 用户token，由用户登录成功后取得 | 否 | f05bf9a2-41fd-4331-bbfc-6b8363503305 |
| User-Agent | 用户代理 | String | 移动应用请求时需确保将此属性添加到请求头中 | 是 | Mozilla/5.0(Windows NT 10.0; Win64;x64)AppleWebKit/537.36(KHTML,like Gecko) Chrome/90.0.4430.212Safari/537.36 |
| sign | 签名信息 | String | (token+timestamp+消息体）SM3摘要，用于防篡改及防重放 | 是 | 7d3ebd79ea3fbcfbe9efe58919d4d0bb |
其中Client-Header中消息结构如下表所示：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| timestamp | 请求时间戳 | Long | 由调用方生成的时间戳，用于服务器的时间差异检查 | 是 | 1626768677928 |
| version | 接口版本号 | String | 采用两级结构“xx.yy”方式，大版本应同时体现在URL中，作为两个独立的借口接口服务，小版本则为微服务同一接口服务内部对差异化处理的标识版本 | 否 | 1.3 |
请求报文示例：
请求消息原始报文示例：
2.3.2. 响应报文规范※
响应报文消息头信息：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| Client-Header | 用户信息响应头 | JSON | 用户信息响应头信息，为JSON字符串，由微服务网关填写 | 是 | {"requestID":"2638416938574123698"} |
| sign | 签名信息 | JSON | 按需实现，(返回消息体）SM3摘要，用于前端对响应报文完整性校验 | 否 | a3cc94d496a543d9f6c318019df9df1fb141 a732f9c7d7122f79bc46757e6699 |
其中Client-Header中消息结构如下表所示：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| requestID | 请求流水号 | Long | 返回由网关补充的请求流水号，用于前端对返回结果进行追踪 | 是 | 2638416938574123698 |
响应报文消息体：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| success | 成功标志 | Boolean | 请求成功失败标志 | 是 | true |
| code | 响应状态码 | Integer | 业务服务响应状态码 | 是 | 200 |
| message | 描述信息 | String | 业务服务响应状态描述信息 | 是 | 成功 |
| data | 业务数据 | JSON | 接口返回的业务数据 | 否 |
响应报文示例：
2.3.3. 微服务网关接口加解密※
如需加密场景，各项目请自行按照国网加密要求进行报文加密处理。
2.4. 微服务接口规范（B类接口）※
2.4.1. 请求响应数据规范※
微服务接口（B类接口），即微服务暴露在微服务网关上的接口，推荐采用上图所示的消息结构，项目组也可根据需要自行扩展。
网关路由：微服务接口在生产环境中，微应用须通过微服务网关访问后台微服务，外部系统须通过接口接入网关访问后台微服务，严禁微服务接口对微应用或外部第三方系统直接暴露。
请求报文头：微服务接口访问场景，即各微服务业务模块提供给的接口，设计时建议采用上图中所示报文结构，在HTTP请求头信息带有来自网关的Client-Header属性，微服务网关在对token鉴权后，会将获取的机构ID[orgID]及用户ID[userID]等信息加入Client-Header，然后转发请求至后续业务服务，以便业务服务快速获取当前服务调用方的用户基础信息，机构名称和用户名称则建议通过共享缓存另行获取。在B类接口访问场景下，请求/响应数据均为明文传输。
异步场景：高并发场景，在满足业务需求的前提下，推荐采用异步请求方式提供接口服务。
2.4.2. 请求报文规范※
微服务请求报文消息头信息：
| 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| 用户信息请求头 | JSON | 用户信息请求头信息，为JSON字符串，由网关填写 | 是 | "requestID":"2638416938574123698", "requestTime":"1626768677928", "terminalType":"10", "clientIP":"11.12.3.45", "orgID":"111000", "userID":"5bb6e538ce76", "version":"1.3" |
其中Client-Header中数据结构如下表所示：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| requestID | 请求流水号 | Long | 由网关生成并自动填补 | 是 | 2638416938574123698 |
| requestTime | 请求时间戳 | Long | 由网关生成并自动填补 | 是 | 1626768677928 |
| terminalType | 终端类型 | String | 由网关根据前端应用传递的User-Agent字段生成 | 是 | 10 |
| clientIP | 客户端IP | String | 客户端IP地址，由网关获取并填写 | 是 | 11.12.3.45 |
| orgID | 机构ID | String | 当前用户机构编码，采用人资机构编码 | 否 | 111000 |
| userID | 用户ID | String | 当前用户在系统内的唯一标识ID | 否 | 5bb6e538ce76 |
| version | 接口版本号 | String | 采用两级结构“xx.yy”方式，用于在接口代码中根据不同的接口小版本号做不同的业务处理 | 否 | 1.3 |
微服务请求报文示例：
请求报文消息示例：
2.4.3. 响应报文规范※
微服务响应报文消息体（响应报文未定义报文头）：
| 属性 | 属性名称 | 类型 | 格式及说明 | 必填 | 示例 |
| success | 成功标志 | Boolean | 请求成功失败标志 | 是 | true |
| code | 响应状态码 | Integer | 业务服务响应状态码 | 是 | 200 |
| message | 描述信息 | String | 业务服务响应状态描述信息 | 是 | 成功 |
| data | 业务数据 | JSON | 接口返回的业务数据 | 否 |
微服务响应报文示例：
2.4.4. 微服务接口定义建议※
单一职责：微服务接口尽量站在业务角度规划，不同的业务采用不同的接口进行定义，例如冻结、解冻为两个业务操作，不要定义为一个更新状态的服务，应该按照业务需求定义为两个独立的业务服务能力。
接口通用：应考虑多渠道接口调用场景，尽量提供全面数据信息，查询接口应尽量支持不同查询条件与排序条件，以减少不必要的接口数量。
支持分页：原则上查询接口在返回列表数据时，应支持分页能力，查询全部数据时应提供最大数据保护。
附录：编码定义参考※
附录1：状态码（code）※
状态码编码参考如下，项目可根据需要自行扩展。
HTTP状态码 body状态码 状态码类型 描述
200 200 通用状态码 操作成功
400 1004 微服务异常 空参数异常
500 500 微服务异常 微服务系统异常
400 2001 网关权限异常 Token为空
400 2002 网关权限异常 Token验证异常
401 401 网关权限异常 暂未登录或token已经过期
403 403 网关权限异常 非法访问
401 4002 网关权限异常 登录失败
500 2005 网关权限异常 注销失败
400 2201 网关安全异常 签名为空
400 2202 网关安全异常 签名校验失败
500 2203 网关安全异常 加密异常
500 2204 网关安全异常 解密异常
400 2205 网关安全异常 包含非法字符
400 2206 网关安全异常 重放攻击
400 2207 网关安全异常 跨站请求伪造攻击
附录2：终端类型（terminalType）※
终端类型 终端名称 描述
11 Web端 来自Web端的调用请求
12 移动端 来自移动端的调用请求
13 第三方接口 来自外部应用的调用请求
14 批处理调用 来自日终批量处理的调用请求
