外贸做的好的网站,苏州互联网公司排名榜,南京设计网站的公司,江苏天宇建设集团网站文章目录 前言先认清一个问题详设文档如何写先看文档脉络详设文档分析需求背景方案概述API定义安全设计性能设计缓存与数据库 总结 前言 这篇文章带读者了解软件开发项目中一个需求的开发详设文档主要包括哪些内容#xff0c;其中重点会给读者分析API设计的规范#xff0c;相… 文章目录 前言先认清一个问题详设文档如何写先看文档脉络详设文档分析需求背景方案概述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得住需求落地。所以我给新人一个建议是先去大公司或者流程规范的项目学流程、学设计这样以后就算只能去小公司你也能混得得心应手从容不迫。
