Go语言接口规范

俗话说, 一流企业做标准, 二流企业做品牌, 三流企业做产品.

制定标准至关重要, 标准规范的制定离不开接口，制定标准的目的就是为了让定义和实现分离，而接口作为完全的抽象，是标准制定的不二之选.

• 项目开发过程中前后端工程师有一个统一的文档进行沟通交流开发
• 一套良好的接口规范可以提升工作效率, 减少沟通障碍.
• 项目维护中或者项目人员更迭，方便后期人员查看、维护

目录

一. 整体要求

1. 简洁

2. 易读

3. 小写

4. 单数

二. 域名规范

三. 请求规范

1. 路径说明

2. HTTP动词

四. 查询参数

1. 筛选(Filtering)

2. 排序(Sorting)

3. 分页(Pagination)

五. 响应规范

1. 统一的返回格式 

2. 错误情况返回

六. http状态码

七. 错误码规范

---

一. 整体要求

API 端点指的是访问该 API 的 URI，主要由协议、主机名、版本、路径和查询字符串及部分组成，例如:

https://api.example.com/v1/users/me/friends?page=1&per_page=10 

我们当前采用Go语言新框架删减版的Restful接口格式, 只使用Get和Post两个HTTP动词.

1. 简洁

• 没有冗余, 容易记忆

Bad	Good
https://api.example.com/service/api/search	https://api.example.com/search

2. 易读

• 意图明确, 容易理解, 不容易易用

Bad	Good
查询单个用户 GET     /sv/u	查询单个用户 GET     /user

3. 小写

使用英文单词, 不要使用拼音, 无大小写混用, 全部使用小写字母(query中使用小驼峰)

Bad	Good
查询单个用户 GET     /getUser/1000	查询单个用户 GET     /user/info?id=1000

4. 单数

资源既可以是单个，也可以是一个集合，比如：user是单个资源，users是集合资源。 由于英文名词的复数规则众多，为了保持接口命名的一致性，我们建议URL里描述集合资源的名词统一使用单数

Bad	Good
查询单个用户 GET     /users/1000  查询一组用户 GET     /users	查询单个用户 GET     /user/info?id=1000  查询一组用户 GET     /user/list

二. 域名规范

可以根据服务分层, 来区分域名, 结合内外网配合服务区分.

三. 请求规范

1. 路径说明

模板: /模块/资源/动作

• 路径主要用来标识一个资源，所以绝大多数（并非所有）情况下要使用名词，结尾结合动词表明操作资源的动作
• 最好的办法还是尽可能避免在 URI 中使用多个单词，比如不用 popular-users 而用 users/popular，或者将一部分内容作为查询参数
• 可以使用模块作为资源区分, 各系统合理规划所关注的领域边界，构建合适的子域通过模块表达。资源表示提供的对应服务，可能是数据服务，可能是能力服务
• 注意: path最多支持三级

示例：

• /报名模块/具体资源/动作
• /order/activity/list
• /order/detail/info
• /order/log/count