当前位置: 首页 > news >正文

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

文章目录

    • 前言
    • 先认清一个问题
    • 详设文档如何写
      • 先看文档脉络
      • 详设文档分析
        • 需求背景
        • 方案概述
        • 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得住需求落地。所以我给新人一个建议是,先去大公司或者流程规范的项目学流程、学设计,这样以后就算只能去小公司,你也能混得得心应手,从容不迫。

相关文章:

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

文章目录 前言先认清一个问题详设文档如何写先看文档脉络详设文档分析需求背景方案概述API定义安全设计性能设计缓存与数据库 总结 前言 这篇文章带读者了解软件开发项目中一个需求的开发详设文档主要包括哪些内容,其中重点会给读者分析API设计的规范,相…...

【Python爬虫实战】正则:多字符匹配、开头与结尾定位、分组技术详解

🌈个人主页:https://blog.csdn.net/2401_86688088?typeblog 🔥 系列专栏:https://blog.csdn.net/2401_86688088/category_12797772.html 目录 前言 一、匹配多个字符 (一)匹配任意多个字符 &#xff0…...

DOIP协议介绍-1

1.DOIP中的GID和EID是什么? 在DOIP(Diagnostics over IP)中,GID(Group Identification)和EID(Entity Identification)是两个重要的标识符,它们各自承担着不同的角色和功…...

探索Python中的多线程与多进程

在Python编程中,多线程和多进程是两个重要的概念,它们被用来提高程序的执行效率。本文将深入探讨这两个概念,并对比它们在Python中的实现方式。 一、多线程 多线程是一种并发执行的程序设计方法。在Python中,我们可以使用thread…...

paypal php 实现详细攻略

一、准备工作 登录 https://www.paypal.com/ 注册一个主账号(选择个人账号、企业账后都可) 申请完成后登录https://developer.paypal.com/ 在后台右侧菜地点击“Accounts”,可以看到系统自动给分配的两个沙箱环境的账号。类型为Personal是个人…...

深入理解Dubbo原理鱼实现,提升职场竞争力

小熊学Java全能学习面试指南:https://www.javaxiaobear.cn 1、RPC RPC(Remote Procedure Call)远程过程调用,它是一种通过网络从远程计算机程序上请求服务。 大白话理解就是:RPC让你用别人家的东西就像自己家的一样。 RPC两个作用&#xff1…...

自动化测试与敏捷开发的重要性

敏捷开发与自动化测试是现代软件开发中两个至关重要的实践,它们相互补充,共同促进了软件质量和开发效率的提升。 敏捷开发的重要性 敏捷开发是一种以人为核心、迭代、循序渐进的软件开发方法。它强调以下几个核心价值观和原则: 个体和交互…...

气膜:冰雪产业的创新解决方案—轻空间

随着冰雪运动的普及和发展,如何在不同季节和地区有效开展冰雪项目,成为了行业内的一个重要课题。气膜作为一种新兴的建筑形式,凭借其独特的优势,正在逐渐成为冰雪产业的创新解决方案。 优越的建筑特性 气膜建筑以其轻便、快速搭建…...

期货配资网/分仓多元化/配资系统服务商

提供期货配资服务的网络平台搭建服务。这些平台致力于为投资者提供高效、便捷的期货投资渠道,通过配资的方式放大投资者的资金杠杆,从而增加其盈利机会。期货配资网一般具有以下特点: 专业服务:提供期货交易、投资管理及信息咨询…...

「漏洞复现」百易云资产管理运营系统 ufile.api.php SQL注入漏洞

0x01 免责声明 请勿利用文章内的相关技术从事非法测试,由于传播、利用此文所提供的信息而造成的任何直接或者间接的后果及损失,均由使用者本人负责,作者不为此承担任何责任。工具来自网络,安全性自测,如有侵权请联系删…...

Vue 3 和 Vue Router 使用 createWebHistory 配置

在 Vue 3 项目中,如果使用 Vue Router 并希望启用 HTML5 History 模式,需要在创建路由器实例时传入 createWebHistory 作为历史模式的配置。此外,还需要确保在生产环境中设置正确的基本路径(base),这样才能…...

Nginx:rewrite指令之flag标志

Nginx 的 rewrite 指令用于根据正则表达式来匹配请求的 URI,并将其重写为新的 URI。rewrite 指令可以包含一个可选的 flag(标志),该标志用于控制重写操作后的行为。 rewrite regex replacement [flag] 一. 常用四种 flag redir…...

C#从零开始学习(如何构建应用)

开始使用 C# 开发使用的软件Visual Studio 2019 文章所有的代码都放在 https://github.com/hikinazimi/head-first-Csharp 创建一个控制台应用 打开Visual Studio 2019 创建项目 选择控制台应用程序 创建后点击运行,就可以在控制台打印Hello World 构建一个游戏(创建WPF项目…...

FCoE简介

数据中心融合网络的发展趋势 如图1所示,传统数据中心组网中,以太网LAN(Local Area Network)用于服务器与服务器、客户端与服务器之间通信,存储区域网络SAN(Storage Area Network)用于服务器与存…...

论文笔记:Template-Based Named Entity Recognition Using BART

论文来源:ACL 2021 Finding 论文链接:https://aclanthology.org/2021.findings-acl.161.pdf 论文代码:GitHub - Nealcly/templateNER: Source code for template-based NER 笔记仅供参考,撰写不易,请勿恶意转载抄袭…...

【Nestjs】从入门到精通(依赖注入)

NestJS 是一个基于 Node.js 的渐进式框架,构建在 Express 或 Fastify 之上,主要用于构建高效、可扩展的服务器端应用程序。它使用 TypeScript 并借鉴了 Angular 的设计理念,采用了依赖注入(IoC, Inversion of Control)…...

C语言函数

1.C语言函数的定义 C源程序是由函数组成的。最简单的程序有一个主函数main(),但实用程序往往由多个函数组成,由主函数调用其他函数,其他函数也可以互相调用。函数是C源程序的基本模块,程序的许多功能是通过对函数模块的调用来实现…...

FLINK SQLTable API 的基本概念及常用API

基本概念 SQL和Table API是Apache Flink提供的两个关系型API,它们被设计用于统一的流和批处理。以下是关于SQL和Table API的基本概念及常用API的详细介绍: 一、基本概念 Table API 定义:Table API是一个为Java、Scala和Python提供的语言集…...

Docker daemon.json配置参数及格式帮助信息

我们知道程序运行,通过修改命令参数或者配置文件配置项,对程序进行修改。Docker也不例外,通过docker.service 增加命令参数或者在/etc/docker/daemon.json中增加配置项均可。 推荐修改daemon.json对docker守护进程进行配置更改(方…...

十月编程语言排行榜~

前言:TIOBE编程语言排行榜通过分析全球开发者的活动、代码搜索和问答社区的流量,提供了编程语言受欢迎度的动态图景。该指数是技术趋势的风向标,揭示了哪些编程语言在技术领域占据主导地位,哪些语言正在快速崛起或逐渐衰退。 ✨✨…...

变量 varablie 声明- Rust 变量 let mut 声明与 C/C++ 变量声明对比分析

一、变量声明设计:let 与 mut 的哲学解析 Rust 采用 let 声明变量并通过 mut 显式标记可变性,这种设计体现了语言的核心哲学。以下是深度解析: 1.1 设计理念剖析 安全优先原则:默认不可变强制开发者明确声明意图 let x 5; …...

【解密LSTM、GRU如何解决传统RNN梯度消失问题】

解密LSTM与GRU:如何让RNN变得更聪明? 在深度学习的世界里,循环神经网络(RNN)以其卓越的序列数据处理能力广泛应用于自然语言处理、时间序列预测等领域。然而,传统RNN存在的一个严重问题——梯度消失&#…...

服务器硬防的应用场景都有哪些?

服务器硬防是指一种通过硬件设备层面的安全措施来防御服务器系统受到网络攻击的方式,避免服务器受到各种恶意攻击和网络威胁,那么,服务器硬防通常都会应用在哪些场景当中呢? 硬防服务器中一般会配备入侵检测系统和预防系统&#x…...

在 Nginx Stream 层“改写”MQTT ngx_stream_mqtt_filter_module

1、为什么要修改 CONNECT 报文? 多租户隔离:自动为接入设备追加租户前缀,后端按 ClientID 拆分队列。零代码鉴权:将入站用户名替换为 OAuth Access-Token,后端 Broker 统一校验。灰度发布:根据 IP/地理位写…...

数据库分批入库

今天在工作中,遇到一个问题,就是分批查询的时候,由于批次过大导致出现了一些问题,一下是问题描述和解决方案: 示例: // 假设已有数据列表 dataList 和 PreparedStatement pstmt int batchSize 1000; // …...

华为云Flexus+DeepSeek征文|DeepSeek-V3/R1 商用服务开通全流程与本地部署搭建

华为云FlexusDeepSeek征文|DeepSeek-V3/R1 商用服务开通全流程与本地部署搭建 前言 如今大模型其性能出色,华为云 ModelArts Studio_MaaS大模型即服务平台华为云内置了大模型,能助力我们轻松驾驭 DeepSeek-V3/R1,本文中将分享如何…...

iOS性能调优实战:借助克魔(KeyMob)与常用工具深度洞察App瓶颈

在日常iOS开发过程中,性能问题往往是最令人头疼的一类Bug。尤其是在App上线前的压测阶段或是处理用户反馈的高发期,开发者往往需要面对卡顿、崩溃、能耗异常、日志混乱等一系列问题。这些问题表面上看似偶发,但背后往往隐藏着系统资源调度不当…...

嵌入式学习笔记DAY33(网络编程——TCP)

一、网络架构 C/S (client/server 客户端/服务器):由客户端和服务器端两个部分组成。客户端通常是用户使用的应用程序,负责提供用户界面和交互逻辑 ,接收用户输入,向服务器发送请求,并展示服务…...

Ubuntu Cursor升级成v1.0

0. 当前版本低 使用当前 Cursor v0.50时 GitHub Copilot Chat 打不开,快捷键也不好用,当看到 Cursor 升级后,还是蛮高兴的 1. 下载 Cursor 下载地址:https://www.cursor.com/cn/downloads 点击下载 Linux (x64) ,…...

DeepSeek源码深度解析 × 华为仓颉语言编程精粹——从MoE架构到全场景开发生态

前言 在人工智能技术飞速发展的今天,深度学习与大模型技术已成为推动行业变革的核心驱动力,而高效、灵活的开发工具与编程语言则为技术创新提供了重要支撑。本书以两大前沿技术领域为核心,系统性地呈现了两部深度技术著作的精华:…...