应用场景

主要用于收集整理前后端开发之间的工作配合，高效高质地实现需求

节约时间，将生命留给其他的事

学习/操作

1.文档阅读

优秀API设计总结

适合写API接口文档的管理工具有哪些？ - 知乎

技术·文档 | 标准API文档规范 1.0 - 知乎

API接口规范 - 简书

2.整理输出

2.1 注意事项

a. 团队[协作开发]之间,要将需求搞明白.

b. 前期设计要做好[尽量后面需要很小的改动],特别是数据库的设计.

c. 团队之间充分讨论需求,并定到伪代码级别,不要急于代码实现.

例如, 使用框架: -- 即，应该严格遵守一定的编程规范以及工作流程

将路由, 控制器, 模型, 文件名, 函数名, 变量, 参数, 开发流程, 分支及相关的命名规范确定下来.

很多东西, 前期约定好, 可以避免后面出现的很多问题.

看似花费很多时间,实际上是值得的.

d. 将所有的讨论,确定,约定的东西,都要落到文档上.

对于前后端分离, 接口的重要不言而喻.

但是不止于接口, 其他确定约定的都要落于文档.

同时, 一旦有改变就要立马修改文档, [需要讨论的,继续讨论,但是要控制时间,有效率的沟通]

文档确定下来, 严格按照文档执行, 实在有问题,需要另行讨论约定.

2.2 接口编写

接口编写,应该清晰简洁,每个团队, 应该结合自身情况确定文档的编写格式.

推荐使用在线文档编写如腾讯在线文档[腾讯文档可设置分享给指定用户]

或者

自行开发一个接口文档系统

或者

使用现有的接口文档工具 -- 如 Swagger

2021-09-29 - 接口文档 - 学习/实践_william_n的博客-CSDN博客

要定义成功 / 失败的请求响应格式，以及状态码，提示信息，要保持统一

文档实例参考

接口编写

1.获取用户列表

url: user/list

请求方式: get

请求参数: 无

响应数据格式: json

返回结果:

成功

{

    'code':1,

    'msg':'success',

    'rows':[

        {

            'name':'test_name',

            'email':'1158885641@qq.com'

        },

        {

            'name':'test_name',

            'email':'1158885641@qq.com'

        }

    ]

}

失败

{

'code':0,

'msg':'failure!'

}

Note：

至于code的取值，可以自行约定即可.

2.3 书写格式，推荐 markdown 语法

Markdown[含GitHub]介绍与用法 - 学习/实践_william_n的博客-CSDN博客_github markdown

2.4 接口测试工具

推荐使用postman

Postman - 学习与使用_william_n的博客-CSDN博客

其实前端也应该安装一个这样的工具，并不是只有后端才需要。

在一个团队中，个人推荐工具使用应保持统一，这样有利于大家将工具使用越来越熟，相互学习借鉴

从而提高工作效率，也有利于保持环境的统一，避免因为工具自身的问题，导致一些不必要的时间成本。

后续补充

...

问题/补充

1.如果接口请求异常，应该返回的响应是什么？

[比如，我看到，很多服务的 API 出错不返回 HTTP 的错误状态码，而是返回个正常的状态码 200，然后在 HTTP Body 里的 JSON 字符串中写着个：error，bla bla error message。这简直就是一种反人类的做法。

我实在不明白为什么会有众多这样的设计。

这让监控怎么做啊？现在，你应该使用 Swagger 的规范了] --- 左耳听风

补充： // 20200825 周二科学馆

如：请求豆瓣的接口，可以作为参考. 有时候我们就是从借鉴模仿学习开始.

https://api.douban.com/v2/movie/in_theaters

{
    'msg':'invalid_apikey, Please contact bd-team@douban.com for authorized access.',
    'code':104,
    'request':'GET /v2/movie/in_theaters'
}

极客时间的接口

{
    'code':-1,
    'error':{
        'code':1001,
        'msg':'request error'
    }
}

补充:

小美：

说下为什么API都返回200，在Body里写错误信息：因为有的运营商会拦截非200请求，然后返回广告????

denofiend：

http header也会拦截

2. 后端服务[如果使用PHP开发]，查询数据库异常，应该怎么处理?

返回给客户端的响应是什么?

TBD

淡淡个人看法。

如果是在框架中开发【目前的项目开发，几乎用的都是基于框架开发，而且是主流框架开发】，框架本身已经做了这个处理，如果数据库异常【这个事情是不可避免，因为网络传输过程本身就是不可靠的】，就会抛出异常，对于开发人员，要做的是，应该手动try...catch, 这里用PHP做说明，其他语言应是差不多的处理机制。

至于返回的结果，应该结合自身的业务逻辑来定

比如

用户查询某个信息，但是后端去查询数据库，出现异常，也许是网络异常，也许是数据库服务器异常，总是没有查询到数据，$ret为空，或者直接抛出异常，那么返回的前端的响应可能就是如下，

{
   'code': 500,
   'message': 'something wrong, plase try later',
   'data': null
}

前端收到响应，也是要服从于业务逻辑，产品运行，

根据code值， 200是正常响应，400也是客户端问题，其实也属于正常响应，但是400响应应属于少数，同时应尽量从前端判断过滤掉这类请求发出，500是服务端异常，这意味着服务出现了问题，应近况修复，真正的好的服务，应该尽量避免500的产生，以及如果产生，立即触发警告，这就需要监控系统，监控 - 解析 API 监控那些事儿_william_n的博客-CSDN博客

04 分布式系统关键技术：全栈监控_william_n的博客-CSDN博客

然后就修复服务。根据服务的重要性，紧急程度，修复的时间要求也不同。

另外，不论是否正常响应，前端是直接展示后端返回的message，还是另外自行展示提示信息，

这也是一个提前商量的事情，期间也可以灵活调整，但是为了便于项目的维护，还是建议要保持统一，

如果是后端返回提示信息，那就统一后端返回显示信息。

参考

优秀API设计总结

适合写API接口文档的管理工具有哪些？ - 知乎

技术·文档 | 标准API文档规范 1.0 - 知乎

Postman 安装及使用入门教程 - Mafly - 博客园

后续补充

文章为作者独立观点，不代表股票程序化软件自动交易接口观点