软件开发行业后端工程师接口开发手册（执行版）

软件开发行业后端工程师接口开发手册（执行版）版本说明：V1.0（2026执行版）适用人员：后端开发工程师、接口联调测试、服务运维人员执行目的：统一项目接口设计、编码、报文、异常、安全、上线标准，解决接口混乱、联调卡顿、规范不统一、线上隐患等问题，实现团队标准化、可落地、可维护的接口开发体系。强制要求：所有新增、迭代接口必须严格遵循本手册规范，旧接口迭代需同步整改适配，禁止私自定义非标接口。第一章基础通用规范（全员强制执行）1.1接口设计核心原则1.语义唯一：一个接口只对应单一业务能力，禁止一个接口承载多混杂业务；2.幂等安全：新增、修改、支付、订单操作类接口必须实现幂等性，避免重复请求导致数据错乱；3.简洁通用：参数精简、字段复用，禁止冗余字段、无效参数；4.兼容迭代：接口迭代优先兼容旧版本，功能性重大变更必须升级版本；5.安全可控：所有接口必填参数校验、权限校验、参数防篡改、防越权。1.2接口版本规范采用路径版本控制，统一前缀管理，适配迭代升级：基础格式：/api/v{版本号}/业务模块/接口资源示例：/api/v1/user/list、/api/v2/order/pay版本迭代规则：1.v1：初始版本，基础业务接口；2.小功能迭代、字段新增不升级版本；3.接口参数、返回结构、核心逻辑不兼容变更，必须升级大版本（v2/v3）。1.3HTTP方法强制规范（RESTful标准）严格区分请求方法，禁止混用、乱用请求方式：1.GET：纯查询操作（列表、详情、统计），无数据修改、无事务操作，参数拼接URL；2.POST：新增数据、复杂提交、批量操作、非幂等业务；3.PUT：全量更新数据，幂等操作；4.PATCH：局部字段更新，增量修改；5.DELETE：删除数据（逻辑删除优先，物理删除慎用）。1.4接口命名规范1.路径统一小写，多单词下划线分隔，禁止驼峰、大写、拼音；2.采用「模块+资源+操作」语义化命名，简洁易懂；3.禁止模糊命名：如/get、/do、/operate等无意义路径；标准示例：✅正确：/api/v1/user/list（用户列表）、/api/v1/order/detail（订单详情）❌错误：/api/getUser、/api/orderOperate、/api/doList第二章统一报文规范（全局统一，禁止自定义）2.1通用响应体结构（强制统一）所有接口返回数据必须遵循统一格式，禁止私自修改结构：PlainText

{

"code":200,//业务状态码

"msg":"操作成功",//前端可直接展示的提示信息

"data":{},//业务数据（对象/数组/空）

"requestId":""//全链路唯一请求ID，用于日志排查

}2.2字段规则说明1.code：业务状态码，200=业务成功，非200全部视为业务失败，禁止用HTTP404/500替代业务异常；2.msg：中文友好提示，简洁通俗，可直接展示给用户，禁止英文、乱码、技术堆栈信息；3.data：成功返回业务数据，无数据返回空对象{}、列表空数据返回[]，禁止返回null；4.requestId：全局唯一链路ID，贯穿请求、日志、数据库操作，用于快速定位线上问题。2.3标准业务状态码体系（强制执行）200：操作成功（通用成功码）2xxx业务逻辑异常2001：参数校验失败2002：数据不存在2003：数据重复/已存在2004：状态不允许操作2005：库存/资源不足3xxx权限账号异常3001：未登录/Token失效3002：权限不足，禁止访问3003：账号冻结/禁用4xxx服务依赖异常4001：第三方接口调用失败4002：服务超时4003：数据库操作异常5xxx系统全局异常5000：系统未知异常2.4请求参数规范1.所有接口参数必须明确：参数名、类型、是否必填、默认值、枚举说明；2.路径参数：用于ID、唯一标识查询，如/user/{id}；3.查询参数：用于分页、筛选、条件查询；4.请求体参数：用于新增、修改、批量操作，统一JSON格式；5.禁止传无效参数、空占位参数，参数命名统一小写下划线格式。2.5分页接口统一规范所有列表分页接口统一入参、出参格式，禁止自定义分页结构：入参（必填）：page_num（页码，默认1）、page_size（每页条数，默认10，最大100）出参统一结构：PlainText

{

"total":0,//总条数

"pages":0,//总页数

"page_num":1,//当前页码

"page_size":10,//每页条数

"list":[]//数据列表

}第三章接口编码开发规范3.1代码分层规范（固定四层架构）严格遵循分层解耦，禁止跨层调用、逻辑混杂：1.Controller层：只做参数接收、权限校验、请求分发、结果返回，禁止写业务逻辑；2.Service层：核心业务逻辑、事务控制、数据组装、业务校验；3.Dao/Mapper层：仅做数据库CRUD操作，无业务逻辑；4.Entity/VO/DTO层：严格分层，实体类对应数据库，VO返回前端，DTO接收参数。3.2参数校验规范（强制落地）1.所有接口入参必须做合法性校验：非空、长度、范围、格式、枚举校验；2.使用统一校验注解，全局异常拦截，统一返回校验失败信息；3.禁止出现：空指针、参数越界、非法字符、格式错误未拦截问题；4.批量操作必须校验集合非空、集合长度限制，防止超大批量压垮数据库。3.3事务使用规范1.新增、修改、删除、批量操作、跨表关联操作必须加事务；2.查询接口禁止加事务，避免无效事务占用资源；3.事务边界统一在Service层，禁止Controller层开启事务；4.严格控制事务粒度，禁止大事务、长事务，避免数据库锁等待、超时。3.4幂等性开发规范1.支付、下单、退款、审核、批量操作接口强制幂等；2.实现方案：唯一令牌、业务唯一主键、状态机校验、分布式锁；3.重复请求直接返回成功，不重复执行业务逻辑，保证数据一致性。第四章异常处理与日志规范4.1全局异常统一处理1.项目必须配置全局异常处理器，统一拦截所有异常；2.禁止接口直接抛出原生异常、堆栈信息暴露给前端；3.区分业务异常、系统异常、参数异常，对应不同状态码；4.所有异常必须携带requestId，方便链路追踪。4.2日志打印规范1.核心接口必须打印：请求参数、响应结果、耗时、操作人、请求IP；2.异常日志必须打印完整堆栈信息，禁止只打印简单提示；3.禁止打印明文密码、Token、手机号、身份证等隐私数据，必须脱敏；4.日志分级：info正常流程、warn异常预警、error系统错误。第五章接口安全与权限规范5.1身份认证规范1.所有业务接口必须携带Token认证，匿名接口统一白名单管理；2.Token过期、失效、非法统一返回3001状态码，前端统一拦截跳转登录；3.禁止接口无认证裸奔、绕过校验直接执行业务逻辑。5.2权限与防越权规范1.后台管理接口必须做角色、菜单、数据三层权限校验；2.严格防止水平越权、垂直越权，用户只能操作自身权限数据；3.所有数据操作接口必须校验操作人身份与数据归属关系。5.3防刷与限流规范1.高频查询、登录、下单、提交接口必须配置限流防刷；2.基于IP、用户ID做频次限制，防止恶意请求、脚本刷接口；3.限流统一返回标准提示：“请求过于频繁，请稍后再试”。5.4数据脱敏规范返回前端敏感数据必须脱敏：1.手机号：138****12342.身份证：110***********12343.银行卡、地址、邮箱等隐私信息统一脱敏处理；4.日志、数据库禁止存储明文敏感数据。第六章联调、测试与上线规范6.1接口文档规范1.所有接口开发完成后，必须同步更新Swagger/接口文档；2.文档必须包含：接口名称、请求方式、路径、参数说明、枚举值、返回示例、异常说明；3.接口迭代必须同步更新文档，禁止文档与代码不一致。6.2自测校验清单（上线必过）1.正常场景：参数正常、业务流程可正常执行；2.异常场景：参数为空、参数非法、数据不存在、权限不足；3.边界场景：分页极值、数据最大值/最小值、批量极值；4.安全场景：越权访问、重复请求、恶意参数；5.性能场景：高频请求、大数据量查询无超时、无卡顿。6.3上线发布规范1.新接口上线先测测试环境，联调通过后方可部署生产；2.接口不兼容变更必须提前同步前端、测试、产品；3.上线后监控接口成功率、报错率、响应耗时，异常立即回滚；4.废弃接口禁止直接删除，先标记废弃、保留兼容，迭代周期后统一清理。第七章性能优化规范7.1查询接口优化1.禁止全表查询、禁止select*，按需查询字段；2.分页查询强制限制最大条数，防止超大结果集；3.高频查询、静态数据启用缓存（Redis），减少数据库压力；4.关联查询合理使用索引，避免慢SQL、全表扫描。7.2接口耗时规范1.普通查询接口：耗时≤200ms；2.复杂列表、统计接口：耗时≤500ms；3.批量、文件、大数据接口：耗时≤1000ms；4.超时接口必须优化SQL、缓存、逻辑，杜绝长期慢接口。第八章违规处罚与落地要求1.所有接口开发必须100%符合本手册规范，代码评审、测试联调严格校验；2.出现非标接口、无校验、无幂等、无权限控制、日志缺失等问题，一律整改重提；3.线上因不规范开发导致数据错乱、安全漏洞、接口报错，追究开发责任人；4.每周迭代必须同步梳理接口规范落地情况，统一整改历史不规范接口。第九章常用接口开发模板（直接复用）1.新增接口：POST/api/v1/xxx/add，参数校验+事务+幂等+成功返回；2.修改接口：PUT/api/v1/xxx/update，局部更新用PATCH，