企业官网建设流程全解析

目录

一、架构与命名规范（REST 优先）

1. 资源命名原则

2. HTTP 方法语义严格对应

二、请求参数设计原则

1. 参数位置区分

2. 统一参数规范

三、统一返回格式（最重要协作原则）

标准返回模板

四、异常与错误处理原则

五、安全设计原则

六、兼容性与版本迭代原则

七、性能与资源约束原则

八、文档、可观测原则

九、拓展：RPC 接口补充（微服务内部）

极简总结（开发快速记忆）

分架构规范、REST 风格、参数规范、安全、兼容性、文档、性能七大模块，后端开发通用标准，前后端协作、微服务都适用。

一、架构与命名规范（REST 优先）

1. 资源命名原则

1. 名词复数表示资源集合，不用动词 错误：/getUser/addOrder正确：
   • 查询用户列表：GET /users
   • 单个用户：GET /users/{id}
   • 创建订单：POST /orders
   • 修改订单：PUT /orders/{id}
   • 删除订单：DELETE /orders/{id}
2. 层级资源用嵌套路径/users/{userId}/orders用户下的所有订单
3. 全部小写，横杠-分隔，禁止下划线、驼峰 正确：/user-address错误：/userAddress/user_address
4. 统一接口前缀区分业务 / 版本
   • 版本放路径（推荐）：/api/v1/users
   • 不建议放 header / 参数，可读性差

2. HTTP 方法语义严格对应

硬性约束：

• GET 不能修改数据；
• POST 不能用于单纯查询；
• 幂等区分：GET/PUT/DELETE 天然幂等；POST 非幂等（重复调用会重复创建）。

二、请求参数设计原则

1. 参数位置区分

1. 路径参数（Path）：唯一标识资源 ID/users/1001
2. 查询参数（Query）：筛选、分页、排序（GET 专用）/orders?page=1&size=10&status=paid
3. 请求体 Body：POST/PUT/PATCH 复杂对象、批量数据 GET禁止携带 Body，部分网关、Nginx 会丢弃。

2. 统一参数规范

1. 分页参数全局统一
   • page：页码，默认 1
   • size：每页条数，限制最大值（如最多 100）
   • sort：排序字段sort=createTime,desc
2. 过滤参数统一命名：status、startTime、endTime
3. 字段命名统一：后端统一下划线 / 驼峰二选一，前后端约定好，不混用
4. 不传参数不赋默认值，后端判空处理；禁止前端传null/ 空字符串混用
5. ID 类数字大值（雪花 ID）返回字符串，避免 JS 精度丢失

三、统一返回格式（最重要协作原则）

全局固定结构，前端不用多套解析逻辑

标准返回模板

{ "code": 200, // 业务状态码 "msg": "success", // 提示文案 "data": {}, // 业务数据，无数据返回null "traceId": "xxx" // 链路追踪ID，排查日志必备 }

1. code 分层设计
   • 200：成功
   • 4xx：客户端错误（参数缺失、权限不足、未登录）
   • 5xx：服务端异常（数据库、内部报错）
   • 自定义业务码：10001 用户不存在、10002 密码错误
2. HTTP 状态码与业务 code 配合
   • 查询成功：HTTP 200
   • 创建成功：HTTP 201
   • 参数错误：HTTP 400
   • 未登录：401，无权限 403
   • 资源不存在：404
   • 服务异常：500
3. 列表分页统一返回结构

"data": { "records": [], "total": 132, "page": 1, "size": 10 }

1. 删除 / 无返回操作 data 返回null，不省略字段

四、异常与错误处理原则

1. 禁止直接抛数据库原生异常、堆栈给前端
2. 错误 msg 分两种：
   • 给用户：简洁易懂（“手机号格式错误”）
   • 后台日志：完整异常栈 + traceId
3. 参数校验统一返回，批量校验返回所有错误字段，不遇到一个就中断

{ "code": 400, "msg": "参数校验失败", "data": [ {"field":"phone","message":"手机号长度必须11位"} ] }

五、安全设计原则

1. 身份认证统一
   • 统一 Token 放在 Header：Authorization: Bearer xxx
   • 不放在 url 参数（日志泄露）
2. 权限控制
   • 接口层校验接口访问权限、数据行权限
   • 越权校验：只能操作自己的数据
3. 防攻击
   • 入参统一过滤 XSS、SQL 注入
   • 敏感数据加密传输（HTTPS 强制）
   • 接口限流防刷：单 IP / 单账号 QPS 限制
4. 敏感信息脱敏 手机号、身份证、银行卡返回脱敏，不明文输出日志、响应
5. 防重放：接口加时间戳 + 签名 sign，防止请求被劫持重复调用

六、兼容性与版本迭代原则

1. 接口向前兼容（核心原则）
   • 新增字段：不能删除原有字段，新增字段默认允许为空
   • 不修改现有字段含义、字段类型
   • 枚举值只能新增，不能删除旧枚举
2. 重大不兼容改动升级版本/api/v2/xxx
3. 废弃接口规范：header 返回Deprecation: true，文档标注下线时间，过渡期保留

七、性能与资源约束原则

1. 分页强制限制最大 size，禁止一次性查全表
2. 大列表支持按需字段投影，fields=id,name减少返回冗余字段
3. 批量操作限制单次最大条数（如批量创建最多 200 条）
4. 大文件 / 大数据流不通过 JSON 返回，提供文件下载接口
5. 高频查询接口增加缓存，避免频繁查库

八、文档、可观测原则

1. 强制生成接口文档（Swagger/Knife4j/OpenAPI） 标注：接口作用、入参、出参、错误码、示例
2. 全链路埋点：traceId、请求耗时、入参日志（脱敏）
3. 接口分级：内部接口 / 对外开放接口区分，对外接口额外限流鉴权

九、拓展：RPC 接口补充（微服务内部）

如果是 Dubbo/GRPC 内部接口，额外遵循：

1. 方法动词命名getUserById、batchSaveOrder
2. 请求 / 响应体单独建 DTO，不复用数据库实体
3. 超时时间统一配置，强制重试、熔断降级
4. 入参必传字段注释，不能传 null 的对象提前约定

极简总结（开发快速记忆）

1. REST 语义清晰，名词资源、HTTP 方法各司其职；
2. 全局统一请求、分页、返回体格式；
3. 入参严格校验，错误信息标准化；
4. HTTPS + 统一鉴权，脱敏防越权防重放；
5. 迭代向前兼容，不破坏老业务；
6. 限流分页控数据量，兼顾性能；
7. 配套完整文档与日志追踪。