API接口清单编制流程
流程编号: INT-PROC-006
流程名称: API接口清单编制流程
版本: v1.0
日期: 2026-03-09
作者: 系统架构师
状态: ✅ 已发布
一、流程概述
1.1 流程目的
建立标准化的API接口清单编制流程，确保系统所有API接口得到完整梳理、规范定义和有效管理，为前后端开发提供清晰的接口契约。
1.2 适用范围
- 新建系统的API接口清单编制
- 现有系统的API接口梳理和文档化
- 接口版本升级时的清单更新
1.3 流程目标
- 确保API接口100%覆盖业务需求
- 建立统一的接口命名和权限编码规范
- 形成可维护的接口文档体系
- 支持接口的版本管理和变更追踪
二、流程图
┌─────────────────────────────────────────────────────────────────┐
│ API接口清单编制流程 │
└─────────────────────────────────────────────────────────────────┘
┌──────────────┐
│ 开始 │
└──────┬───────┘
│
▼
┌──────────────┐ 否 ┌──────────────┐
│ 需求分析完成? │────────────▶│ 等待需求 │
└──────┬───────┘ └──────────────┘
│ 是
▼
┌──────────────┐
│ 识别业务模块 │
│ - 用户管理 │
│ - 角色权限 │
│ - 组织架构 │
│ - 系统管理 │
└──────┬───────┘
│
▼
┌──────────────┐
│ 梳理功能点 │
│ 每个模块 │
└──────┬───────┘
│
▼
┌──────────────┐
│ 设计接口列表 │
│ - 接口名称 │
│ - HTTP方法 │
│ - 接口路径 │
│ - 权限要求 │
└──────┬───────┘
│
▼
┌──────────────┐
│ 编制接口清单 │
│ 文档 │
└──────┬───────┘
│
▼
┌──────────────┐ 否 ┌──────────────┐
│ 内部评审通过? │────────────▶│ 修改完善 │
└──────┬───────┘ └──────┬───────┘
│ 是 │
│◄───────────────────────────┘
▼
┌──────────────┐ 否 ┌──────────────┐
│ 正式评审通过? │────────────▶│ 修改完善 │
└──────┬───────┘ └──────┬───────┘
│ 是 │
│◄───────────────────────────┘
▼
┌──────────────┐
│ 建立接口基线 │
└──────┬───────┘
│
▼
┌──────────────┐
│ 结束 │
└──────────────┘三、流程步骤
步骤1: 需求分析确认
输入: 业务需求文档(BRD)、功能规格说明书
输出: 需求分析确认单
负责人: 系统架构师
检查项:
- [√] 业务需求文档已评审通过
- [√] 功能模块划分清晰
- [√] 用户角色和权限需求明确
交付物:
- 需求分析确认单
步骤2: 识别业务模块
输入: 需求分析确认单、系统功能架构
输出: 业务模块清单
负责人: 系统架构师
活动:
- 根据系统功能架构识别核心业务模块
- 为每个模块分配模块代码
- 确定模块间的依赖关系
模块代码规范:
| 模块名称 | 模块代码 | 基础路径 | 说明 |
|---|---|---|---|
| 用户管理 | USER | /api/v1/users | 用户CRUD、状态管理 |
| 角色权限 | ROLE | /api/v1/roles | 角色、权限管理 |
| 组织架构 | ORG | /api/v1/orgs | 部门、岗位管理 |
| 系统管理 | SYS | /api/v1/sys | 认证、字典、日志 |
交付物:
- 业务模块清单
步骤3: 梳理功能点
输入: 业务模块清单、功能规格说明书
输出: 功能点清单
负责人: 系统架构师、业务分析师
活动:
- 针对每个业务模块梳理功能点
- 识别功能点的CRUD操作
- 识别特殊业务操作
功能点梳理模板:
markdown
### 模块: [模块名称]
| 功能点 | 操作类型 | 业务规则 |
|-------|---------|---------|
| 用户管理 | CRUD | 支持批量操作 |
| 用户状态 | 更新 | 启用/禁用 |
| 密码管理 | 更新 | 重置/修改密码 |交付物:
- 功能点清单
步骤4: 设计接口列表
输入: 功能点清单、RESTful API设计规范
输出: 接口设计草稿
负责人: 系统架构师
活动:
- 为每个功能点设计对应的API接口
- 确定HTTP方法
- 设计接口路径
- 定义权限编码
接口设计规范:
| 功能类型 | HTTP方法 | 路径示例 | 说明 |
|---|---|---|---|
| 查询列表 | GET | /users | 支持分页、筛选 |
| 创建资源 | POST | /users | 请求体包含数据 |
| 查询详情 | GET | /users/{id} | 路径参数传递ID |
| 更新资源 | PUT | /users/{id} | 全量更新 |
| 部分更新 | PATCH | /users/{id} | 部分字段更新 |
| 删除资源 | DELETE | /users/{id} | 物理/逻辑删除 |
| 业务操作 | POST | /users/{id}/enable | 特定业务动作 |
权限编码规范:
格式: {模块}:{操作}
| 操作 | 权限编码 | 说明 |
|---|---|---|
| 查询 | user:read | 读取权限 |
| 创建 | user:create | 新增权限 |
| 更新 | user:update | 修改权限 |
| 删除 | user:delete | 删除权限 |
| 全部 | user:* | 所有权限 |
交付物:
- 接口设计草稿
步骤5: 编制接口清单文档
输入: 接口设计草稿
输出: API接口清单文档
负责人: 系统架构师
文档结构:
markdown
# API接口清单
## 一、概述
- 文档目的
- 接口统计
- 接口规范
## 二、接口清单
### 2.1 [模块名称]
| 序号 | 接口名称 | 方法 | 路径 | 说明 | 详细文档 |
## 三、接口依赖关系
## 四、权限映射表
## 五、版本规划
## 六、相关文档
## 七、修订记录交付物:
01-api-interface-list.md
步骤6: 内部评审
输入: API接口清单文档
输出: 内部评审意见
负责人: 系统架构师、后端架构师
评审检查项:
| 序号 | 评审项 | 检查内容 |
|---|---|---|
| 1 | 接口完整性 | 是否覆盖所有功能点 |
| 2 | 接口规范性 | 是否符合RESTful规范 |
| 3 | 命名一致性 | URL命名是否统一 |
| 4 | 权限设计 | 权限编码是否规范 |
| 5 | 版本规划 | 版本策略是否合理 |
评审结果处理:
- 通过: 进入正式评审
- 不通过: 修改完善后重新内部评审
交付物:
- 内部评审记录
步骤7: 正式评审
输入: API接口清单文档(内部评审通过版)
输出: 正式评审报告
负责人: 技术总监、系统架构师、后端架构师、前端负责人
评审议程:
- 接口清单整体介绍 (10分钟)
- 分模块接口评审 (30分钟)
- 问题讨论 (15分钟)
- 评审结论 (5分钟)
评审结论:
- 通过: 建立接口基线
- 有条件通过: 修改指定问题后建立基线
- 不通过: 重新设计后再次评审
交付物:
- 接口评审报告
- 评审签字确认表
步骤8: 建立接口基线
输入: 正式评审报告
输出: 接口基线文档
负责人: 系统架构师
基线内容:
- 基线版本号
- 基线日期
- 包含的接口清单
- 签字确认记录
基线管理:
- 基线文档纳入配置管理
- 后续接口变更需走变更流程
交付物:
- 接口基线文档
四、角色职责
| 角色 | 职责 |
|---|---|
| 系统架构师 | 主导接口清单编制，设计接口规范，组织评审 |
| 业务分析师 | 提供业务需求，协助功能点梳理 |
| 后端架构师 | 评审接口设计可行性，确认技术实现方案 |
| 前端负责人 | 评审接口易用性，确认前端调用方式 |
| 技术总监 | 主持正式评审，批准接口基线 |
五、输入输出清单
5.1 输入文档
| 序号 | 文档名称 | 文档编号 | 说明 |
|---|---|---|---|
| 1 | 业务需求文档 | SYS-BRD-001 | 业务功能需求 |
| 2 | 功能规格说明书 | SYS-FRS-001 | 详细功能规格 |
| 3 | RESTful API设计规范 | SYS-INT-STD-001 | 接口设计标准 |
5.2 输出文档
| 序号 | 文档名称 | 文档编号 | 说明 |
|---|---|---|---|
| 1 | API接口清单 | SYS-INT-API-001 | 接口清单文档 |
| 2 | 接口评审报告 | SYS-INT-REV-003 | 评审结论 |
| 3 | 接口基线文档 | SYS-INT-REV-005 | 基线确认 |
六、质量标准
6.1 接口覆盖率
- 功能点覆盖率: 100%
- 业务场景覆盖率: ≥95%
6.2 接口规范性
- RESTful规范符合度: 100%
- 命名规范符合度: 100%
- 权限编码规范符合度: 100%
6.3 文档质量
- 文档完整性: 100%
- 评审通过率: 100%
七、相关流程
八、修订记录
| 版本 | 日期 | 作者 | 变更内容 |
|---|---|---|---|
| 1.0 | 2026-03-09 | 系统架构师 | 初始版本，定义API接口清单编制流程 |