# M2 - 基础用户系统 - 详细接口设计 ## 1. 概述 本文档基于M2阶段的数据库设计和产品需求，提供完整的RESTful API接口设计方案。所有接口遵循以下原则： - **RESTful规范**：使用标准HTTP方法和状态码 - **统一响应格式**：所有接口返回统一的JSON格式 - **安全性**：JWT认证、权限控制、数据验证 - **高性能**：合理的缓存策略、分页设计 - **版本控制**：API版本化管理 ### 基础URL ``` https://api.starzh.com/v1 ``` ### 统一响应格式 ```json { "code": 0, // 业务状态码，0表示成功 "message": "success", // 提示信息 "data": {}, // 响应数据 } ``` ### 统一错误码规范 - 0: 成功 - 400xx: 客户端错误（参数错误、验证失败等） - 401xx: 认证错误 - 403xx: 权限错误 - 404xx: 资源不存在 - 409xx: 资源冲突 - 500xx: 服务器错误 --- ## 2. 认证模块 (Authentication) ### 2.1 用户注册 #### 需求描述 允许新用户通过邮箱注册账号，需要邮箱验证激活。支持基本的用户名、密码规则校验。 #### 接口名称 用户注册接口 #### 设计原因 - 提供用户自主注册功能 - 通过邮箱验证确保用户真实性 - 防止恶意注册和垃圾账号 #### 请求类型 POST #### 接口路径 `/auth/register` #### 接口参数 ```typescript { username: string; // 用户名，3-50字符，字母开头，仅包含字母数字下划线 email: string; // 邮箱地址，需符合邮箱格式 password: string; // 密码，8-100字符，必须包含大小写字母和数字 confirmPassword: string; // 确认密码，需与password一致 captcha: string; // 图形验证码 captchaId: string; // 验证码ID } ``` **参数约束原因**： - username: 限制长度和字符类型，防止特殊字符引起的安全问题 - password: 强密码策略，提高账户安全性 - captcha: 防止机器人批量注册 #### 响应分类 - 成功：201 Created - 注册成功，发送激活邮件 - 失败： - 400 Bad Request - 参数验证失败 - 409 Conflict - 用户名或邮箱已存在 #### 响应格式 ```json // 成功响应 { "code": 0, "message": "注册成功，请查收邮件激活账号", "data": { "userId": 1234567890, "username": "john_doe", "email": "john@example.com", "status": "inactive" } } // 失败响应示例 { "code": 40901, "message": "用户名已被占用", "data": null } ``` #### 开发思路 1. 参数验证层：使用Elysia的t验证器进行参数校验 2. 业务逻辑层： - 验证图形验证码 - 检查用户名和邮箱唯一性 - 密码使用bcrypt加密（成本因子12） - 生成用户记录（状态为inactive） - 生成激活token并存入Redis（24小时过期） - 发送激活邮件（异步队列） 3. 数据访问层：使用事务确保数据一致性 4. 日志记录：记录注册操作到sys_operation_logs --- ### 2.2 用户登录 #### 需求描述 支持用户名或邮箱登录，实现登录失败次数限制，防止暴力破解。 #### 接口名称 用户登录接口 #### 设计原因 - 提供安全的身份认证机制 - 支持多种登录方式提升用户体验 - 防止暴力破解攻击 #### 请求类型 POST #### 接口路径 `/auth/login` #### 接口参数 ```typescript { account: string; // 用户名或邮箱 password: string; // 密码 captcha?: string; // 验证码（连续失败3次后必填） captchaId?: string; // 验证码ID rememberMe?: boolean; // 记住我，默认false } ``` #### 响应分类 - 成功：200 OK - 登录成功，返回token - 失败： - 401 Unauthorized - 用户名或密码错误 - 423 Locked - 账号被锁定 #### 响应格式 ```json // 成功响应 { "code": 0, "message": "登录成功", "data": { "token": "eyJhbGciOiJIUzI1NiIs...", "refreshToken": "xxxx-xxxx-xxxx", "expiresIn": 7200, "user": { "id": 1234567890, "username": "john_doe", "nickname": "John", "avatar": "https://...", "roles": ["user"] } } } ``` #### 开发思路 1. 查询用户（支持username或email） 2. 检查账号状态和锁定状态 3. 验证密码 4. 处理登录失败： - 增加失败次数 - 超过5次锁定30分钟 - 3次失败后要求验证码 5. 登录成功： - 清除失败次数 - 生成JWT token - 更新最后登录信息 - 记录登录日志 --- ### 2.3 刷新Token #### 需求描述 使用refreshToken换取新的accessToken，实现无感续期。 #### 接口名称 Token刷新接口 #### 设计原因 - 短期accessToken + 长期refreshToken模式 - 提高安全性，减少token泄露风险 - 实现用户无感续期体验 #### 请求类型 POST #### 接口路径 `/auth/refresh` #### 接口参数 ```typescript { refreshToken: string; // 刷新令牌 } ``` #### 响应格式 ```json { "code": 0, "message": "刷新成功", "data": { "token": "new-access-token", "expiresIn": 7200 } } ``` #### 开发思路 1. 验证refreshToken有效性 2. 检查用户状态 3. 生成新的accessToken 4. 可选：轮转refreshToken 5. 记录刷新日志 --- ### 2.4 账号激活 #### 需求描述 用户通过邮件中的链接或验证码激活账号。 #### 接口名称 账号激活接口 #### 设计原因 - 验证邮箱真实性 - 防止垃圾注册 - 提高用户质量 #### 请求类型 POST #### 接口路径 `/auth/activate` #### 接口参数 ```typescript { token: string; // 激活令牌（从邮件链接获取） // 或 email: string; // 邮箱 code: string; // 6位数字激活码 } ``` #### 响应格式 ```json { "code": 0, "message": "账号激活成功", "data": { "userId": 1234567890, "username": "john_doe", "status": "active" } } ``` #### 开发思路 1. 验证激活token或激活码 2. 检查是否过期 3. 更新用户状态为active 4. 删除Redis中的激活信息 5. 发送欢迎邮件 6. 记录激活日志 --- ### 2.5 退出登录 #### 需求描述 用户主动退出登录，清除token。 #### 接口名称 退出登录接口 #### 设计原因 - 用户主动结束会话 - 清除服务端缓存 - 增强安全性 #### 请求类型 POST #### 接口路径 `/auth/logout` #### 请求头 ``` Authorization: Bearer ``` #### 响应格式 ```json { "code": 0, "message": "退出成功", "data": null } ``` #### 开发思路 1. 获取当前token 2. 加入token黑名单（Redis） 3. 清除用户相关缓存 4. 记录退出日志 --- ## 3. 用户管理模块 (User Management) ### 3.1 获取当前用户信息 #### 需求描述 获取当前登录用户的详细信息，包括基本信息、角色、权限、组织等。 #### 接口名称 获取当前用户信息接口 #### 设计原因 - 前端需要用户信息进行界面渲染 - 权限控制需要用户角色和权限信息 - 统一的用户信息获取入口 #### 请求类型 GET #### 接口路径 `/users/me` #### 请求头 ``` Authorization: Bearer ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "id": 1234567890, "username": "john_doe", "email": "john@example.com", "mobile": "13800138000", "nickname": "John", "avatar": "https://...", "gender": 1, "birthday": "1990-01-01", "bio": "Hello world", "status": "active", "lastLoginAt": "2024-01-01T12:00:00Z", "roles": [ { "id": 1, "code": "admin", "name": "管理员" } ], "permissions": [ { "code": "user:read", "name": "查看用户", "type": "api" } ], "organizations": [ { "id": 1, "name": "技术部", "isPrimary": true, "position": "工程师" } ], "tags": [ { "id": 1, "name": "VIP", "color": "#ff4d4f" } ] } } ``` #### 开发思路 1. 从JWT token中获取用户ID 2. 查询用户基本信息 3. 并行查询关联信息： - 用户角色（包含权限快照） - 用户组织 - 用户标签 4. 整合权限信息（角色权限去重） 5. 使用Redis缓存（5分钟过期） --- ### 3.2 用户列表查询 #### 需求描述 分页查询用户列表，支持多条件筛选和排序。 #### 接口名称 用户列表查询接口 #### 设计原因 - 管理员需要查看和管理所有用户 - 支持灵活的查询条件满足不同场景 - 分页设计避免大数据量查询 #### 请求类型 GET #### 接口路径 `/users` #### 接口参数 ```typescript // Query Parameters { page?: number; // 页码，默认1 pageSize?: number; // 每页数量，默认20，最大100 keyword?: string; // 搜索关键词（用户名/邮箱/手机号/昵称） status?: string; // 用户状态 roleId?: number; // 角色ID organizationId?: number; // 组织ID tagId?: number; // 标签ID startDate?: string; // 注册开始时间 endDate?: string; // 注册结束时间 sortBy?: string; // 排序字段：createdAt,lastLoginAt sortOrder?: string; // 排序方向：asc,desc } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "items": [ { "id": 1234567890, "username": "john_doe", "email": "john@example.com", "mobile": "138****8000", "nickname": "John", "avatar": "https://...", "status": "active", "roles": ["admin", "user"], "organizations": ["技术部"], "tags": ["VIP"], "loginCount": 100, "lastLoginAt": "2024-01-01T12:00:00Z", "createdAt": "2023-01-01T00:00:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 100, "totalPages": 5 } } } ``` #### 开发思路 1. 参数验证和权限检查（需要user:read权限） 2. 构建查询条件： - 关键词模糊查询 - 状态精确匹配 - 关联表过滤（角色、组织、标签） - 时间范围查询 3. 执行分页查询（使用索引优化） 4. 批量查询关联信息（减少N+1查询） 5. 数据脱敏（手机号中间4位） --- ### 3.3 创建用户 #### 需求描述 管理员创建新用户，可直接设置角色、组织等信息。 #### 接口名称 创建用户接口 #### 设计原因 - 管理员需要批量创建用户 - 可预设用户角色和组织 - 支持直接激活状态 #### 请求类型 POST #### 接口路径 `/users` #### 接口参数 ```typescript { username: string; email: string; password: string; mobile?: string; nickname?: string; status?: string; // 默认active gender?: number; birthday?: string; bio?: string; roleIds?: number[]; // 角色ID数组 organizationIds?: Array<{ id: number; isPrimary: boolean; position?: string; }>; // 组织信息 tagIds?: number[]; // 标签ID数组 sendNotification?: boolean; // 是否发送通知邮件 } ``` #### 响应格式 ```json { "code": 0, "message": "创建成功", "data": { "id": 1234567890, "username": "new_user", "email": "new@example.com", "status": "active" } } ``` #### 开发思路 1. 权限检查（需要user:create权限） 2. 参数验证（唯一性检查） 3. 使用事务处理： - 创建用户记录 - 分配角色 - 分配组织 - 分配标签 4. 发送通知邮件（可选） 5. 记录操作日志 --- ### 3.4 更新用户信息 #### 需求描述 更新用户基本信息和关联信息。 #### 接口名称 更新用户信息接口 #### 设计原因 - 支持用户自主修改个人信息 - 管理员可修改用户所有信息 - 分离基本信息和关联信息更新 #### 请求类型 PUT #### 接口路径 `/users/{userId}` #### 接口参数 ```typescript { email?: string; mobile?: string; nickname?: string; avatar?: string; gender?: number; birthday?: string; bio?: string; // 以下字段需要管理员权限 status?: string; roleIds?: number[]; organizationIds?: Array<{ id: number; isPrimary: boolean; position?: string; }>; tagIds?: number[]; } ``` #### 响应格式 ```json { "code": 0, "message": "更新成功", "data": { "id": 1234567890, "username": "john_doe", "email": "john@example.com", "updatedAt": "2024-01-01T12:00:00Z" } } ``` #### 开发思路 1. 权限检查： - 用户可修改自己的基本信息 - 管理员可修改所有信息 - root用户信息限制修改 2. 参数验证（邮箱唯一性等） 3. 使用乐观锁防止并发冲突 4. 更新关联信息时先删后增 5. 清除相关缓存 --- ### 3.5 修改密码 #### 需求描述 用户修改自己的密码，需要验证原密码。 #### 接口名称 修改密码接口 #### 设计原因 - 用户自主管理密码 - 增强账户安全性 - 防止未授权修改 #### 请求类型 PUT #### 接口路径 `/users/me/password` #### 接口参数 ```typescript { oldPassword: string; // 原密码 newPassword: string; // 新密码 confirmPassword: string; // 确认新密码 } ``` #### 响应格式 ```json { "code": 0, "message": "密码修改成功", "data": null } ``` #### 开发思路 1. 验证原密码正确性 2. 验证新密码符合规则 3. 更新密码（bcrypt加密） 4. 清除所有该用户的token 5. 发送密码修改通知邮件 --- ### 3.6 重置密码 #### 需求描述 用户忘记密码时通过邮箱重置。 #### 接口名称 申请重置密码接口 #### 设计原因 - 用户忘记密码的补救措施 - 通过邮箱验证身份 - 防止恶意重置 #### 请求类型 POST #### 接口路径 `/users/password/reset-request` #### 接口参数 ```typescript { email: string; captcha: string; captchaId: string; } ``` #### 响应格式 ```json { "code": 0, "message": "重置邮件已发送", "data": null } ``` #### 开发思路 1. 验证邮箱存在 2. 验证图形验证码 3. 生成重置token（6位数字或链接） 4. 存入Redis（30分钟过期） 5. 发送重置邮件 6. 限制发送频率（1分钟内不可重复） --- ### 3.7 确认重置密码 #### 需求描述 使用重置token设置新密码。 #### 接口名称 确认重置密码接口 #### 请求类型 POST #### 接口路径 `/users/password/reset-confirm` #### 接口参数 ```typescript { token: string; // 重置token email: string; // 邮箱 newPassword: string; // 新密码 confirmPassword: string; // 确认密码 } ``` #### 响应格式 ```json { "code": 0, "message": "密码重置成功", "data": null } ``` #### 开发思路 1. 验证token有效性和匹配性 2. 验证新密码规则 3. 更新用户密码 4. 删除重置token 5. 清除用户所有token 6. 发送重置成功通知 --- ### 3.8 删除用户 #### 需求描述 软删除用户，保留数据用于审计。 #### 接口名称 删除用户接口 #### 设计原因 - 满足用户注销需求 - 保留数据用于审计 - 支持误删恢复 #### 请求类型 DELETE #### 接口路径 `/users/{userId}` #### 响应格式 ```json { "code": 0, "message": "删除成功", "data": null } ``` #### 开发思路 1. 权限检查（需要user:delete权限） 2. 检查是否为root用户（禁止删除） 3. 检查是否为自己（需要二次确认） 4. 更新deleted_at字段 5. 清除用户所有会话 6. 记录删除操作日志 --- ### 3.9 批量操作用户 #### 需求描述 批量启用、禁用、删除用户。 #### 接口名称 批量操作用户接口 #### 设计原因 - 提高管理效率 - 支持批量处理 - 减少重复操作 #### 请求类型 POST #### 接口路径 `/users/batch` #### 接口参数 ```typescript { userIds: number[]; // 用户ID数组 action: string; // 操作类型：enable,disable,delete } ``` #### 响应格式 ```json { "code": 0, "message": "操作成功", "data": { "success": 10, "failed": 0, "errors": [] } } ``` #### 开发思路 1. 权限检查 2. 过滤掉root用户 3. 批量执行操作 4. 记录操作结果 5. 返回执行统计 --- ## 4. 角色管理模块 (Role Management) ### 4.1 角色树查询 #### 需求描述 查询角色树形结构，支持权限继承展示。 #### 接口名称 角色树查询接口 #### 设计原因 - 角色具有层级关系需要树形展示 - 支持权限继承机制 - 便于理解角色体系 #### 请求类型 GET #### 接口路径 `/roles/tree` #### 接口参数 ```typescript { status?: string; // 过滤状态 withPermissions?: boolean; // 是否包含权限信息 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": [ { "id": 1, "code": "super_admin", "name": "超级管理员", "description": "拥有所有权限", "status": "active", "isSystem": true, "permissionCount": 50, "children": [ { "id": 2, "code": "admin", "name": "管理员", "pid": 1, "children": [] } ] } ] } ``` #### 开发思路 1. 查询所有角色（使用path字段优化） 2. 构建树形结构（递归或迭代） 3. 统计每个角色的权限数量 4. 使用Redis缓存（角色变更时失效） --- ### 4.2 创建角色 #### 需求描述 创建新角色并分配权限，支持角色继承。 #### 接口名称 创建角色接口 #### 设计原因 - 灵活的角色管理支持业务扩展 - 权限继承减少重复配置 - 下级角色权限不能超过上级 #### 请求类型 POST #### 接口路径 `/roles` #### 接口参数 ```typescript { code: string; // 角色代码，唯一 name: string; // 角色名称 description?: string; // 角色描述 pid?: number; // 父角色ID status?: string; // 状态，默认active permissionIds: number[]; // 权限ID数组 } ``` #### 响应格式 ```json { "code": 0, "message": "创建成功", "data": { "id": 10, "code": "editor", "name": "编辑员", "path": "/1/2/10/", "level": 3 } } ``` #### 开发思路 1. 权限检查（需要role:create权限） 2. 验证角色代码唯一性 3. 验证父角色存在性 4. 检查权限分配合法性： - 获取父角色所有权限 - 确保新角色权限是父角色权限的子集 5. 使用事务创建： - 创建角色记录 - 计算并设置path和level - 分配权限 - 生成权限快照 6. 清除角色缓存 --- ### 4.3 更新角色信息 #### 需求描述 更新角色基本信息，不包括权限。 #### 接口名称 更新角色信息接口 #### 设计原因 - 角色信息可能需要调整 - 分离基本信息和权限更新 - 防止误操作 #### 请求类型 PUT #### 接口路径 `/roles/{roleId}` #### 接口参数 ```typescript { name?: string; description?: string; status?: string; sortOrder?: number; } ``` #### 开发思路 1. 权限检查（需要role:update权限） 2. 检查是否为系统角色（限制修改） 3. 更新角色信息 4. 清除角色缓存 --- ### 4.4 更新角色权限 #### 需求描述 动态调整角色权限，支持批量操作。 #### 接口名称 更新角色权限接口 #### 设计原因 - 业务变化需要调整权限 - 支持灵活的权限管理 - 保证权限继承一致性 #### 请求类型 PUT #### 接口路径 `/roles/{roleId}/permissions` #### 接口参数 ```typescript { permissionIds: number[]; // 新的权限ID数组（全量） } ``` #### 响应格式 ```json { "code": 0, "message": "权限更新成功", "data": { "roleId": 10, "permissionCount": 20, "addedCount": 5, "removedCount": 3 } } ``` #### 开发思路 1. 检查角色是否为系统角色 2. 验证权限合法性（不超过父角色） 3. 对比新旧权限，计算差异 4. 使用事务更新： - 删除旧权限关联 - 创建新权限关联 - 更新权限快照 5. 级联更新子角色（移除超出的权限） 6. 清除相关用户的权限缓存 --- ### 4.5 删除角色 #### 需求描述 删除角色，处理关联关系。 #### 接口名称 删除角色接口 #### 设计原因 - 清理无用角色 - 保持系统整洁 - 防止权限泄露 #### 请求类型 DELETE #### 接口路径 `/roles/{roleId}` #### 开发思路 1. 权限检查（需要role:delete权限） 2. 检查是否为系统角色（禁止删除） 3. 检查是否有用户使用该角色 4. 检查是否有子角色 5. 软删除角色 6. 清除相关缓存 --- ### 4.6 角色用户查询 #### 需求描述 查询某个角色下的所有用户。 #### 接口名称 角色用户查询接口 #### 设计原因 - 了解角色使用情况 - 便于角色管理 - 支持用户迁移 #### 请求类型 GET #### 接口路径 `/roles/{roleId}/users` #### 接口参数 ```typescript { page?: number; pageSize?: number; keyword?: string; } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "items": [ { "id": 123, "username": "john_doe", "email": "john@example.com", "assignedAt": "2024-01-01T00:00:00Z" } ], "pagination": { "page": 1, "pageSize": 20, "total": 50 } } } ``` --- ### 4.7 角色排序接口 #### 需求描述 支持手动调整角色的显示顺序，保证同级角色按指定顺序展示。 #### 接口名称 角色排序接口 #### 设计原因 - 角色列表需要按重要性排序 - 下拉选择时按业务优先级展示 - 管理员需要控制显示顺序 #### 请求类型 PUT #### 接口路径 `/roles/sort` #### 接口参数 ```typescript { items: Array<{ id: number; // 角色ID sortOrder: number; // 新的排序号 }> } ``` #### 响应格式 ```json { "code": 0, "message": "排序更新成功", "data": { "updated": 5 } } ``` #### 开发思路 1. 权限检查（需要role:sort权限） 2. 批量更新sortOrder字段 3. 确保同级别角色排序唯一性 4. 清除角色缓存 5. 返回更新结果 --- ### 4.8 拖拽排序接口 #### 需求描述 支持前端拖拽方式调整角色顺序，更直观的操作方式。 #### 接口名称 拖拽排序接口 #### 设计原因 - 提供更好的用户体验 - 直观的排序操作 - 减少误操作 #### 请求类型 PUT #### 接口路径 `/roles/{roleId}/move` #### 接口参数 ```typescript { targetIndex: number; // 目标位置索引（0开始） pid?: number; // 父级ID，如果跨级移动 } ``` #### 响应格式 ```json { "code": 0, "message": "移动成功", "data": { "roleId": 10, "oldIndex": 2, "newIndex": 0, "affectedRoles": [8, 9, 10] } } ``` #### 开发思路 1. 计算目标位置的sortOrder值 2. 更新被移动角色的sortOrder 3. 调整其他角色的sortOrder（避免冲突） 4. 如果跨级移动，同时更新pid 5. 清除相关缓存 --- ## 5. 权限管理模块 (Permission Management) ### 5.1 权限树查询 #### 需求描述 查询权限树形结构，按类型分组展示。 #### 接口名称 权限树查询接口 #### 设计原因 - 权限具有层级关系（菜单-页面-按钮） - 便于权限分配时的选择 - 支持不同类型权限的管理 #### 请求类型 GET #### 接口路径 `/permissions/tree` #### 接口参数 ```typescript { type?: string; // 权限类型：menu,button,api,data status?: string; // 状态过滤 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": [ { "id": 1, "code": "system", "name": "系统管理", "type": "menu", "children": [ { "id": 2, "code": "system:user", "name": "用户管理", "type": "menu", "children": [ { "id": 3, "code": "user:read", "name": "查看用户", "type": "api", "resource": "user", "action": "read" } ] } ] } ] } ``` #### 开发思路 1. 查询权限列表 2. 按类型分组 3. 构建树形结构 4. 使用Redis缓存 --- ### 5.2 创建权限 #### 需求描述 创建新的权限节点。 #### 接口名称 创建权限接口 #### 设计原因 - 新功能需要新权限 - 灵活的权限扩展 - 支持细粒度控制 #### 请求类型 POST #### 接口路径 `/permissions` #### 接口参数 ```typescript { code: string; // 权限代码 name: string; // 权限名称 type: string; // 权限类型 resource?: string; // 资源标识 action?: string; // 操作标识 pid?: number; // 父权限ID description?: string; // 描述 meta?: object; // 元数据（如图标、路由） } ``` #### 开发思路 1. 权限检查（需要permission:create权限） 2. 验证权限代码唯一性 3. 验证父权限存在性 4. 创建权限记录 5. 清除权限缓存 --- ### 5.3 批量创建权限 #### 需求描述 支持批量导入权限配置。 #### 接口名称 批量创建权限接口 #### 设计原因 - 新模块上线需要批量添加权限 - 提高配置效率 - 支持权限模板导入 #### 请求类型 POST #### 接口路径 `/permissions/batch` #### 接口参数 ```typescript { permissions: Array<{ code: string; name: string; type: string; resource?: string; action?: string; pid?: number; description?: string; }> } ``` #### 响应格式 ```json { "code": 0, "message": "批量创建成功", "data": { "success": 10, "failed": 0, "errors": [] } } ``` #### 开发思路 1. 批量验证权限代码唯一性 2. 验证父权限存在性 3. 使用事务批量插入 4. 返回执行结果统计 5. 清除权限缓存 --- ### 5.4 更新权限 #### 需求描述 更新权限信息。 #### 接口名称 更新权限接口 #### 设计原因 - 权限名称或描述可能需要调整 - 元数据更新（如菜单图标） - 状态变更 #### 请求类型 PUT #### 接口路径 `/permissions/{permissionId}` #### 接口参数 ```typescript { name?: string; description?: string; status?: string; meta?: object; sortOrder?: number; } ``` #### 开发思路 1. 权限检查 2. 更新权限信息 3. 清除权限缓存 4. 通知相关角色缓存更新 --- ### 5.5 删除权限 #### 需求描述 删除权限节点及其子权限。 #### 接口名称 删除权限接口 #### 设计原因 - 功能下线需要删除权限 - 保持权限体系整洁 - 防止权限泄露 #### 请求类型 DELETE #### 接口路径 `/permissions/{permissionId}` #### 开发思路 1. 权限检查（需要permission:delete权限） 2. 检查是否有角色使用该权限 3. 递归删除子权限 4. 清除相关缓存 --- ### 5.6 权限检查接口 #### 需求描述 检查当前用户是否拥有特定权限。 #### 接口名称 权限检查接口 #### 设计原因 - 前端动态控制界面元素 - 细粒度的功能控制 - 实时权限验证 #### 请求类型 POST #### 接口路径 `/permissions/check` #### 接口参数 ```typescript { permissions: string[]; // 权限代码数组 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "user:read": true, "user:create": true, "user:delete": false } } ``` #### 开发思路 1. 获取当前用户所有权限 2. 批量检查请求的权限 3. 返回权限检查结果 --- ### 5.7 权限排序接口 #### 需求描述 调整权限的显示顺序，特别是菜单权限的排序。 #### 接口名称 权限排序接口 #### 设计原因 - 菜单权限需要控制显示顺序 - 影响前端菜单渲染顺序 - 提升用户体验 #### 请求类型 PUT #### 接口路径 `/permissions/sort` #### 接口参数 ```typescript { items: Array<{ id: number; sortOrder: number; }> } ``` #### 开发思路 1. 权限检查（需要permission:sort权限） 2. 批量更新权限排序 3. 确保同级权限排序唯一 4. 清除权限缓存 5. 通知前端刷新菜单 --- ## 6. 组织架构模块 (Organization Management) ### 6.1 组织树查询 #### 需求描述 查询组织架构树，支持人员统计。 #### 接口名称 组织架构树查询接口 #### 设计原因 - 直观展示组织层级关系 - 便于用户分配和管理 - 支持组织人员统计 #### 请求类型 GET #### 接口路径 `/organizations/tree` #### 接口参数 ```typescript { type?: string; // 组织类型 status?: string; // 状态 withStats?: boolean; // 是否包含统计信息 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": [ { "id": 1, "code": "ROOT", "name": "星撰集团", "type": "company", "userCount": 100, "children": [ { "id": 2, "code": "TECH", "name": "技术部", "type": "department", "userCount": 30, "leader": { "id": 123, "name": "张三" }, "children": [] } ] } ] } ``` #### 开发思路 1. 查询组织列表 2. 构建树形结构 3. 如需统计： - 批量查询用户组织关联 - 聚合统计各组织人数 4. 查询负责人信息 5. 使用Redis缓存 --- ### 6.2 创建组织 #### 需求描述 创建新的组织节点。 #### 接口名称 创建组织接口 #### 设计原因 - 组织架构需要动态调整 - 支持业务扩展 - 灵活的组织管理 #### 请求类型 POST #### 接口路径 `/organizations` #### 接口参数 ```typescript { code: string; // 组织代码 name: string; // 组织名称 fullName?: string; // 组织全称 type: string; // 组织类型 pid?: number; // 父组织ID leaderId?: number; // 负责人ID address?: string; // 地址 phone?: string; // 电话 description?: string; // 描述 } ``` #### 开发思路 1. 权限检查（需要organization:create权限） 2. 验证组织代码唯一性 3. 验证父组织存在性 4. 创建组织记录 5. 计算path和level 6. 清除组织缓存 --- ### 6.3 调整组织架构 #### 需求描述 支持拖拽调整组织层级关系。 #### 接口名称 调整组织架构接口 #### 设计原因 - 组织架构会随业务发展调整 - 支持灵活的组织变更 - 保持数据完整性 #### 请求类型 PUT #### 接口路径 `/organizations/{organizationId}/move` #### 接口参数 ```typescript { targetPid: number; // 目标父组织ID targetIndex?: number; // 目标位置索引 } ``` #### 响应格式 ```json { "code": 0, "message": "调整成功", "data": { "id": 10, "oldPath": "/1/2/10/", "newPath": "/1/3/10/", "affectedCount": 5 } } ``` #### 开发思路 1. 验证目标组织存在性 2. 检查是否会形成循环 3. 使用事务更新： - 更新pid - 重新计算path和level - 更新所有子组织的path - 调整排序 4. 记录组织变更日志 5. 清除相关缓存 --- ### 6.4 组织人员管理 #### 需求描述 管理组织内的人员分配。 #### 接口名称 组织人员分配接口 #### 设计原因 - 灵活的人员调动 - 支持批量操作 - 记录调动历史 #### 请求类型 POST #### 接口路径 `/organizations/{organizationId}/users` #### 接口参数 ```typescript { action: string; // 操作：add,remove,move userIds: number[]; // 用户ID数组 position?: string; // 职位（添加时使用） isPrimary?: boolean; // 是否主组织 targetOrgId?: number; // 目标组织ID（移动时使用） } ``` #### 开发思路 1. 权限检查 2. 验证用户和组织存在性 3. 执行批量操作： - add: 添加用户到组织 - remove: 从组织移除用户 - move: 移动到其他组织 4. 记录人员变动日志 --- ### 6.5 删除组织 #### 需求描述 删除组织节点，处理人员安置。 #### 接口名称 删除组织接口 #### 设计原因 - 组织调整需要删除节点 - 确保人员妥善安置 - 保持数据完整性 #### 请求类型 DELETE #### 接口路径 `/organizations/{organizationId}` #### 接口参数 ```typescript { handleUsers?: string; // 人员处理方式：moveToParent,remove targetOrgId?: number; // 目标组织ID（自定义迁移时使用） } ``` #### 开发思路 1. 权限检查（需要organization:delete权限） 2. 检查是否有子组织 3. 处理组织内人员 4. 软删除组织 5. 清除相关缓存 --- ### 6.6 组织架构排序接口 #### 需求描述 调整同级组织的显示顺序。 #### 接口名称 组织排序接口 #### 设计原因 - 组织架构显示需要符合实际层级 - 重要部门需要前置显示 - 便于组织管理 #### 请求类型 PUT #### 接口路径 `/organizations/{pid}/sort` #### 接口参数 ```typescript { items: Array<{ id: number; sortOrder: number; }> } ``` #### 响应格式 ```json { "code": 0, "message": "组织排序更新成功", "data": { "parentId": 1, "updated": 3 } } ``` #### 开发思路 1. 验证所有组织都属于同一父级 2. 批量更新sortOrder 3. 清除组织架构缓存 4. 返回更新结果 --- ## 7. 字典管理模块 (Dictionary Management) ### 7.1 字典类型树查询 #### 需求描述 查询字典类型的树形结构，支持分类管理。 #### 接口名称 字典类型树查询接口 #### 设计原因 - 字典类型支持分类管理 - 便于字典的组织和查找 - 区分系统字典和业务字典 #### 请求类型 GET #### 接口路径 `/dictionaries/types/tree` #### 响应格式 ```json { "code": 0, "message": "success", "data": [ { "id": 1, "code": "system", "name": "系统字典", "isSystem": true, "children": [ { "id": 10, "code": "user_status", "name": "用户状态", "itemCount": 4 } ] } ] } ``` #### 开发思路 1. 查询所有字典类型 2. 构建树形结构 3. 统计每个类型的字典项数量 4. 使用Redis缓存 --- ### 7.2 获取字典项 #### 需求描述 根据字典类型获取所有字典项，支持树形字典。 #### 接口名称 获取字典项接口 #### 设计原因 - 前端下拉框等组件需要字典数据 - 支持动态配置 - 减少硬编码 #### 请求类型 GET #### 接口路径 `/dictionaries/items` #### 接口参数 ```typescript { typeCode: string; // 字典类型代码 tree?: boolean; // 是否返回树形结构 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": [ { "key": "active", "value": "active", "label": "正常", "labelEn": "Active", "color": "#52c41a", "sortOrder": 1, "extra": {} } ] } ``` #### 开发思路 1. 根据typeCode查询字典类型 2. 查询该类型下的所有字典项 3. 如果是树形字典，构建树结构 4. 使用Redis缓存（字典变更少） --- ### 7.3 创建字典类型 #### 需求描述 创建新的字典类型。 #### 接口名称 创建字典类型接口 #### 设计原因 - 业务扩展需要新字典 - 灵活的配置管理 - 支持分类组织 #### 请求类型 POST #### 接口路径 `/dictionaries/types` #### 接口参数 ```typescript { code: string; // 字典类型代码 name: string; // 字典类型名称 pid?: number; // 父类型ID description?: string; // 描述 sortOrder?: number; // 排序号 } ``` #### 开发思路 1. 权限检查（需要dictionary:create权限） 2. 验证代码唯一性 3. 验证父权限存在性 4. 创建字典类型 5. 清除字典缓存 --- ### 7.4 批量更新字典项 #### 需求描述 支持批量更新字典项，保持顺序。 #### 接口名称 批量更新字典项接口 #### 设计原因 - 字典项通常需要批量维护 - 保持显示顺序的一致性 - 提高维护效率 #### 请求类型 PUT #### 接口路径 `/dictionaries/types/{typeId}/items/batch` #### 接口参数 ```typescript { items: Array<{ id?: number; // 有ID为更新，无ID为新增 key: string; value: string; label: string; labelEn?: string; pid?: number; sortOrder: number; status?: string; color?: string; extra?: object; }> } ``` #### 响应格式 ```json { "code": 0, "message": "批量更新成功", "data": { "created": 3, "updated": 5, "deleted": 2 } } ``` #### 开发思路 1. 验证字典类型存在 2. 检查是否为系统字典 3. 验证key在类型内唯一 4. 使用事务处理： - 标记删除不在列表中的项 - 更新已存在的项 - 创建新项 5. 清除字典缓存 --- ### 7.5 导出字典数据 #### 需求描述 导出字典配置用于备份或迁移。 #### 接口名称 导出字典数据接口 #### 设计原因 - 配置备份需求 - 环境间迁移 - 批量导入导出 #### 请求类型 GET #### 接口路径 `/dictionaries/export` #### 接口参数 ```typescript { typeIds?: number[]; // 指定类型ID，不传则导出全部 format?: string; // 导出格式：json,excel } ``` #### 响应格式 ``` Content-Type: application/octet-stream Content-Disposition: attachment; filename="dictionaries_20240101.json" ``` #### 开发思路 1. 查询指定的字典类型和项 2. 构建导出数据结构 3. 根据格式生成文件 4. 返回文件流 --- ### 7.6 字典项排序接口 #### 需求描述 调整字典项的显示顺序，影响下拉框等组件的选项顺序。 #### 接口名称 字典项排序接口 #### 设计原因 - 下拉框选项需要按业务逻辑排序 - 常用选项前置显示 - 提升用户操作效率 #### 请求类型 PUT #### 接口路径 `/dictionaries/types/{typeId}/items/sort` #### 接口参数 ```typescript { items: Array<{ id: number; sortOrder: number; }> } ``` #### 响应格式 ```json { "code": 0, "message": "字典项排序更新成功", "data": { "typeId": 1, "updated": 4 } } ``` #### 开发思路 1. 验证所有字典项都属于指定类型 2. 批量更新sortOrder 3. 清除字典缓存 4. 返回更新结果 --- ## 8. 标签管理模块 (Tag Management) ### 8.1 标签列表查询 #### 需求描述 查询标签列表，支持按类型和使用频率排序。 #### 接口名称 标签列表查询接口 #### 设计原因 - 便于标签的统一管理 - 支持热门标签展示 - 不同类型标签分开管理 #### 请求类型 GET #### 接口路径 `/tags` #### 接口参数 ```typescript { type?: string; // 标签类型 keyword?: string; // 搜索关键词 sortBy?: string; // 排序：usageCount,createdAt page?: number; pageSize?: number; } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "items": [ { "id": 1, "name": "VIP", "type": "user", "color": "#ff4d4f", "usageCount": 100, "description": "VIP用户" } ], "pagination": { "page": 1, "pageSize": 20, "total": 50 } } } ``` #### 开发思路 1. 构建查询条件 2. 执行分页查询 3. 根据sortBy排序 4. 返回标签列表 --- ### 8.2 创建标签 #### 需求描述 创建新的标签。 #### 接口名称 创建标签接口 #### 设计原因 - 灵活的标签扩展 - 支持自定义标签 - 统一标签管理 #### 请求类型 POST #### 接口路径 `/tags` #### 接口参数 ```typescript { name: string; // 标签名称 type: string; // 标签类型 color?: string; // 标签颜色 description?: string; // 描述 } ``` #### 开发思路 1. 权限检查（需要tag:create权限） 2. 验证标签名称唯一性（同类型内） 3. 创建标签记录 4. 返回创建结果 --- ### 8.3 标签使用统计 #### 需求描述 统计标签使用情况，生成报表。 #### 接口名称 标签使用统计接口 #### 设计原因 - 了解标签使用情况 - 优化标签体系 - 数据分析支持 #### 请求类型 GET #### 接口路径 `/tags/statistics` #### 接口参数 ```typescript { type?: string; // 标签类型 top?: number; // 返回前N个 startDate?: string; // 统计开始时间 endDate?: string; // 统计结束时间 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "summary": { "totalTags": 50, "totalUsage": 1000, "avgUsage": 20 }, "topTags": [ { "id": 1, "name": "VIP", "usageCount": 100, "percentage": 10 } ], "trend": [ { "date": "2024-01-01", "count": 20 } ] } } ``` #### 开发思路 1. 统计基础数据 2. 查询热门标签 3. 计算使用趋势 4. 整合返回结果 --- ### 8.4 标签智能推荐 #### 需求描述 根据用户特征智能推荐标签。 #### 接口名称 标签推荐接口 #### 设计原因 - 提高标签使用的准确性 - 基于规则引擎自动打标 - 减少人工维护成本 #### 请求类型 POST #### 接口路径 `/tags/recommend` #### 接口参数 ```typescript { userId: number; // 用户ID type: string; // 推荐类型 limit?: number; // 推荐数量限制 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "recommendations": [ { "tagId": 1, "tagName": "活跃用户", "confidence": 0.95, "reason": "最近30天登录20次" } ] } } ``` #### 开发思路 1. 获取用户特征数据 2. 执行推荐规则： - 活跃度规则（登录次数、最后登录时间） - 贡献度规则（内容创作数量） - 消费规则（VIP等级） 3. 计算置信度 4. 返回推荐标签列表 5. 记录推荐日志 --- ### 8.5 批量打标签 #### 需求描述 为多个用户批量添加或移除标签。 #### 接口名称 批量打标签接口 #### 设计原因 - 提高运营效率 - 支持批量操作 - 灵活的标签管理 #### 请求类型 POST #### 接口路径 `/tags/batch-assign` #### 接口参数 ```typescript { userIds: number[]; // 用户ID数组 tagIds: number[]; // 标签ID数组 action: string; // 操作：add,remove } ``` #### 响应格式 ```json { "code": 0, "message": "批量操作成功", "data": { "success": 50, "failed": 0, "errors": [] } } ``` #### 开发思路 1. 权限检查 2. 验证用户和标签存在性 3. 批量执行操作 4. 更新标签使用统计 5. 返回执行结果 --- ### 8.6 标签排序接口 #### 需求描述 调整标签的显示顺序，支持热门标签前置。 #### 接口名称 标签排序接口 #### 设计原因 - 热门标签需要前置显示 - 按业务重要性排序 - 提升标签选择效率 #### 请求类型 PUT #### 接口路径 `/tags/sort` #### 接口参数 ```typescript { type?: string; // 标签类型，为空则排序全部 items: Array<{ id: number; sortOrder: number; }> } ``` #### 响应格式 ```json { "code": 0, "message": "标签排序更新成功", "data": { "type": "user", "updated": 6 } } ``` #### 开发思路 1. 权限检查（需要tag:sort权限） 2. 验证标签类型一致性 3. 批量更新sortOrder 4. 更新标签缓存 5. 返回更新结果 --- ## 9. 通用功能接口 ### 9.1 图形验证码 #### 需求描述 生成图形验证码，用于注册、登录等场景。 #### 接口名称 获取图形验证码接口 #### 设计原因 - 防止机器人攻击 - 增强系统安全性 - 限制恶意请求 #### 请求类型 GET #### 接口路径 `/common/captcha` #### 接口参数 ```typescript { type?: string; // 验证码类型：image,math width?: number; // 图片宽度，默认120 height?: number; // 图片高度，默认40 } ``` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "captchaId": "xxxx-xxxx-xxxx", "captchaImage": "data:image/svg+xml;base64,..." } } ``` #### 开发思路 1. 生成随机验证码文本 2. 生成SVG或图片 3. 存储到Redis（5分钟过期） 4. 返回Base64编码的图片 --- ### 9.2 文件上传 #### 需求描述 通用文件上传接口，支持头像等文件上传。 #### 接口名称 文件上传接口 #### 设计原因 - 统一的文件上传入口 - 支持多种文件类型 - 安全的文件处理 #### 请求类型 POST #### 接口路径 `/common/upload` #### 请求格式 multipart/form-data #### 接口参数 ```typescript { file: File; // 文件 type: string; // 文件类型：avatar,document,image isPublic?: boolean; // 是否公开访问，默认false } ``` #### 响应格式 ```json { "code": 0, "message": "上传成功", "data": { "fileId": "file123456", "url": "https://oss.starzh.com/xxx.jpg", "size": 102400, "name": "avatar.jpg", "type": "image/jpeg" } } ``` #### 开发思路 1. 验证文件类型和大小 2. 生成唯一文件名 3. 上传到OSS或本地存储 4. 记录文件信息到数据库 5. 返回文件访问URL --- ### 9.3 邮件发送 #### 需求描述 统一的邮件发送接口，用于系统通知。 #### 接口名称 邮件发送接口（内部接口） #### 设计原因 - 统一邮件发送逻辑 - 支持模板化 - 便于监控和管理 #### 请求类型 POST #### 接口路径 `/internal/email/send` #### 接口参数 ```typescript { to: string[]; // 收件人邮箱数组 template: string; // 邮件模板ID params: object; // 模板参数 attachments?: Array<{ // 附件 filename: string; content: string; }>; } ``` #### 开发思路 1. 加载邮件模板 2. 渲染模板内容 3. 调用邮件服务发送 4. 记录发送日志 5. 处理发送失败（重试机制） --- ### 9.4 系统健康检查 #### 需求描述 提供系统健康状态检查接口。 #### 接口名称 健康检查接口 #### 设计原因 - 监控系统状态 - 负载均衡健康检查 - 快速发现问题 #### 请求类型 GET #### 接口路径 `/health` #### 响应格式 ```json { "code": 0, "message": "success", "data": { "status": "healthy", "version": "1.0.0", "uptime": 3600, "services": { "database": "ok", "redis": "ok", "elasticsearch": "ok" } } } ``` #### 开发思路 1. 检查数据库连接 2. 检查Redis连接 3. 检查其他服务状态 4. 返回综合健康状态 --- ### 9.5 数据导入导出 #### 需求描述 支持批量数据的导入导出功能。 #### 接口名称 数据导出接口 #### 设计原因 - 数据备份需求 - 批量数据处理 - 数据迁移支持 #### 请求类型 POST #### 接口路径 `/common/export` #### 接口参数 ```typescript { module: string; // 模块：users,roles,organizations format: string; // 格式：excel,csv,json filters?: object; // 过滤条件 fields?: string[]; // 导出字段 } ``` #### 响应格式 ```json { "code": 0, "message": "导出任务已创建", "data": { "taskId": "export-123456", "status": "processing" } } ``` #### 开发思路 1. 创建导出任务 2. 异步处理数据查询和转换 3. 生成导出文件 4. 通过WebSocket或轮询通知完成 5. 提供下载链接 --- ### 9.6 通用排序接口 #### 需求描述 提供通用的排序接口，支持多种数据类型的排序。 #### 接口名称 通用排序接口 #### 设计原因 - 统一的排序逻辑 - 减少代码重复 - 便于维护和扩展 #### 请求类型 PUT #### 接口路径 `/common/sort` #### 接口参数 ```typescript { table: string; // 表名：roles,permissions,organizations,tags scopeField?: string; // 范围字段：pid,typeId等 scopeValue?: any; // 范围值 items: Array<{ id: number; sortOrder: number; }> } ``` #### 响应格式 ```json { "code": 0, "message": "排序更新成功", "data": { "table": "roles", "scope": "pid=1", "updated": 5 } } ``` #### 开发思路 1. 验证表名和字段的安全性 2. 权限检查（根据表名动态判断） 3. 构建更新SQL 4. 批量更新排序字段 5. 清除相关缓存 6. 返回更新结果 --- ## 10. 安全性设计 ### 10.1 认证机制 - **JWT Token认证** - AccessToken有效期2小时 - RefreshToken有效期7天 - Token黑名单机制 - 支持多设备登录管理 ### 10.2 权限控制 - **基于RBAC的权限模型** - 接口级别的权限控制 - 数据级别的权限过滤 - 动态权限加载 - 权限缓存优化 ### 10.3 安全措施 - **传输安全** - 所有接口强制HTTPS - 敏感数据加密传输 - 防重放攻击（时间戳+nonce） - **输入验证** - 参数类型和格式验证 - SQL注入防护（参数化查询） - XSS防护（输入过滤和转义） - 文件上传安全检查 - **访问控制** - IP白名单（管理接口） - 请求频率限制 - 并发连接限制 - 异常行为检测 ### 10.4 日志审计 - **操作日志** - 记录所有写操作 - 包含用户、时间、IP、操作内容 - 敏感操作实时告警 - **安全日志** - 登录失败记录 - 权限拒绝记录 - 异常请求记录 --- ## 11. 性能优化 ### 11.1 缓存策略 | 缓存类型 | 缓存内容 | 过期时间 | 更新策略 | |---------|---------|---------|---------| | 用户信息缓存 | 基本信息、角色、权限 | 5分钟 | 主动更新+过期刷新 | | 角色权限缓存 | 角色树、权限快照 | 1小时 | 变更时删除 | | 字典缓存 | 字典类型和项 | 24小时 | 变更时删除 | | 验证码缓存 | 图形验证码 | 5分钟 | 使用后删除 | ### 11.2 查询优化 - **索引优化** - 基于查询模式设计索引 - 定期分析慢查询日志 - 避免全表扫描 - **查询优化** - 使用预编译语句 - 避免N+1查询 - 合理使用JOIN和子查询 - 大数据量分页优化 ### 11.3 并发控制 - **限流策略** - 接口级别限流（令牌桶算法） - 用户级别限流 - IP级别限流 - **资源控制** - 数据库连接池管理 - Redis连接池管理 - 异步任务队列 ### 11.4 异步处理 - **异步任务** - 邮件发送 - 文件处理 - 数据导入导出 - 统计计算 --- ## 12. 错误处理 ### 12.1 错误码规范 | 错误码范围 | 说明 | 示例 | |-----------|------|------| | 0 | 成功 | 操作成功 | | 400xx | 客户端错误 | 40001-参数错误 | | 401xx | 认证错误 | 40101-未登录 | | 403xx | 权限错误 | 40301-无权限 | | 404xx | 资源不存在 | 40401-用户不存在 | | 409xx | 资源冲突 | 40901-用户名已存在 | | 423xx | 资源锁定 | 42301-账号被锁定 | | 429xx | 请求过多 | 42901-请求频率超限 | | 500xx | 服务器错误 | 50001-内部错误 | | 503xx | 服务不可用 | 50301-服务维护中 | ### 12.2 错误响应格式 ```json { "code": 40001, "message": "参数验证失败：用户名长度必须在3-50个字符之间", "data": { "field": "username", "value": "ab", "rule": "minLength" }, } ``` ### 12.3 错误处理最佳实践 - **友好的错误提示** - 使用用户能理解的语言 - 提供解决建议 - 避免暴露技术细节 - **错误日志记录** - 记录完整的错误堆栈 - 包含请求上下文 - 分级记录（info/warn/error） - **错误监控告警** - 错误率监控 - 关键错误实时告警 - 错误趋势分析 --- ## 13. 接口版本管理 ### 13.1 版本策略 - **URL版本化** - 格式：`/api/v{n}/...` - 主版本号变更表示不兼容更新 - 向后兼容原则 ### 13.2 版本迁移 - **废弃通知** - 提前3个月通知 - 响应头添加废弃警告 - 提供迁移文档 - **版本共存** - 新旧版本并行运行 - 逐步迁移用户 - 设置旧版本下线时间 --- ## 14. 开发规范总结 ### 14.1 接口设计原则 - **RESTful规范** - 使用标准HTTP方法 - 资源导向的URL设计 - 合理使用状态码 - **一致性原则** - 统一的命名规范 - 统一的响应格式 - 统一的错误处理 ### 14.2 最佳实践 - **幂等性设计** - GET/PUT/DELETE操作幂等 - POST操作防重复提交 - **分页设计** - 统一分页参数 - 限制最大返回条数 - 提供总数统计 - **数据安全** - 敏感数据脱敏 - 防止信息泄露 - 输入验证和过滤 ### 14.3 文档规范 - **接口文档** - 使用Swagger自动生成 - 包含请求和响应示例 - 说明业务场景 - **变更记录** - 记录所有API变更 - 说明变更原因 - 提供升级指南 --- ## 15. 附录 ### 15.1 常用正则表达式 ```javascript // 用户名：3-50位字母数字下划线，字母开头 const USERNAME_REGEX = /^[a-zA-Z][a-zA-Z0-9_]{2,49}$/; // 邮箱 const EMAIL_REGEX = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; // 手机号（中国大陆） const MOBILE_REGEX = /^1[3-9]\d{9}$/; // 强密码：8-100位，包含大小写字母和数字 const PASSWORD_REGEX = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)[a-zA-Z\d@$!%*?&]{8,100}$/; ``` ### 15.2 时间格式约定 - 统一使用ISO 8601格式 - 示例：`2024-01-01T12:00:00Z` - 时区：统一使用UTC时间 ### 15.3 分页参数约定 - `page`: 页码，从1开始 - `pageSize`: 每页条数，默认20，最大100 - `total`: 总记录数 - `totalPages`: 总页数 --- 本接口设计文档为M2基础用户系统的完整API规范，后续开发应严格遵循本文档的设计要求。