带你学习如何编写一篇API详设文档以及给新人提点建议

前言

  这篇文章带读者了解软件开发项目中一个需求的开发详设文档主要包括哪些内容，其中重点会给读者分析API设计的规范，相信这篇文章看完对你绝对是有收获的。因为对于程序员来说，只会按着API设计文档做代码实现的话那只是属于初级程序员的水平，更有价值的能力是自己有将需求转化为实现方案详细设计的能力，成为有设计能力的程序员对团队来说你的性价比更高，更有升职加薪的价值，尤其对于后端程序员来说一定要培养设计能力，因为在开发团队中，详设文档的输出主要由架构或者后端成长起来的设计角色主导。

先认清一个问题

  对于初入后端开发的人来说，往往认为后端的设计就是接口调用的设计，请求方式、URL、返回值、错误码这些，事实上在一个严谨重设计的团队中，你要输出的详设文档中远不止这些，即使是接口本身的定义设计也没你想得那么简单，是有一套经验总结出的规范需要遵循的。只不过在一些小公司，前后端就几个人的团队里，大家沟通方便，口口相传，几个人把事情说明白了就能开发了，规范啥的全凭自觉，心想管它呢，好不好维护那是以后的事儿。但是我还是建议后端开发朋友们即使是在小公司，即使是不要求开发规范以及不要求输出详设文档的团队，也要养成规范的习惯，或者说至少要知道怎样才是规范的，太随意的话保不齐哪天埋个坑给自己坑到了，简单说就是，文档可以不写，但是自己写接口的时候还是要注意规范。

详设文档如何写

先看文档脉络

  我用word自己编写一个主脉络大家先看看一篇详设文档必须要有的内容有哪些：

详设文档分析

  首先，大家要知道详设文档主要目的不是写给自己看的，详设文档产生的背景是成熟规范的开发团队中有方案评审的流程，设计人员写的详设文档是要给对接你的其他开发、测试讲解的，大家一起讨论你的方案，并且存档后未来新人接手维护的时候你可以把文档给新人看（虽然实际中一般是看代码，但是如果你文档中流程图和设计思路写得够细，对新人来说帮助还是很大的）。接下来我们来细看详设文档的每个部分写什么，怎么写。

需求背景

  需求背景的意义主要是方案评审时参会的开发和测试中可能有人是不知道需求背景的，比如有的测试是测试组长安排他来测这个需求，但是测试组长也没给他细说过背景，而是上会来听。所以需求背景主要是讲清楚需求的主要内容是什么（不用特别细，不是需求评审，只是给啥也不清楚的人一个背景提示）？以及为什么要做这个需求？

方案概述

  方案概述是要写清楚开发方案涉及到哪些端（比如后端、web端、APP、三方平台之类的），以及这些端之间需要做哪些交互，相当于需求整体的一个方案设计脉络，并且输出一个交互流程图，毕竟开会听一遍不一定别人马上能吸收，你说的东西在文档上要有详细的体现。

API定义

  这是文档中最核心的一部分，对于后端设计来说，最起码客户端调用你的请求与传参、收参需要你有明确的接口定义，这部分内容需要你提供API名称、具体定义（请求方式、鉴权方式、URL、请求和返回参数定义、错误码）等详细具体的内容。说起来都是很简单的东西，但其中其实需要你做很多规范的思考。特别是后端属于微服务架构的情况来说，规范尤为重要，举两个例子：
  比如你的接口是外部接口提供给客户端调用的还是说是后端服务之间调用的内部接口？两种情况URL规范当然需要区分，假如外部接口是/v1/user/info，那内部接口的话定义可以是/v1/internal/user/info，并且内部接口和外部接口的鉴权方案是有区别的，要求细的团队，URL中名词统一单数还是复数表示都有规范。

  另一个例子是错误码，现在软件开发项目中有两种返回规范，一种是使用200、400、401、500等不同http状态码对应不同错误情况，200的时候返回成功的数据结构体、其他情况返回错误码；另一种规范更常用，统一使用200错误码，不管成功还是失败返回一个统一数据结构，对于APP来说更喜欢这种，因为他们框架默认只会取200状态码的数据，不是200默认是服务器失败不取数。在微服务中，错误码的编号定义也有要求，比如你有十个微服务，对于成功、服务器错误、鉴权失败这类统一的场景来说，错误码当然要定义成一样的，但是每个服务自己的业务错误码各不相同，这时候要考虑错误码冲突的问题，要编号分段，比如1~1000是给A服务的，1001到2000是给B服务的，避免不同的错误提示用了同一个编号，那你让客户端怎么知道该提示啥呢？

安全设计

  安全设计如果细说的话可以单独写很多篇文章，细节太多了，但是在详设中只需要写这个方案涉及到的安全设计，比如接口的鉴权、如果是账号登录这类的功能还涉及账号与密码的加密，账号使用可逆的加密算法，密码的话只能使用不可逆（不能解密出明文）的加密算法。

性能设计

  这是给测试一个性能指标，对于有性能要求的团队来说，如果你有接口响应比较慢，要特别说明一下。

缓存与数据库

  方案中哪些数据用到了缓存与持久化数据库，要给出具体的存储设计与表设计。

总结

  做设计是一个很锻炼人的工作，首先输出详设文档需要你基于项目现状思考设计技术实现方案，并且在方案评审时你要能给别人讲清楚，相当于设计能力与沟通表达能力都能涉及到，对于初入行的新人来说，一定要努力往这方向靠，而且在成熟的项目团队中，做设计的人有时候是较为独立的角色，还能做点管理的事情，简单说就是你设计，然后你还需要给一些普通开发针对方案分工，这个其实可以理解，因为在团队中能做设计的人都是对项目内容、功能前世今生比较熟悉的人。可以这么说，从普通的编码角色走向设计角色，是一个非常重要的蜕变，直接决定你的升职加薪，有设计的能力，你就算去小公司，没人带你也hold得住需求落地。所以我给新人一个建议是，先去大公司或者流程规范的项目学流程、学设计，这样以后就算只能去小公司，你也能混得得心应手，从容不迫。