LLD（详细设计文档）输出标准模板
文档版本：V1.0
修订日期：【YYYY-MM-DD】
文档状态：【草稿 / 评审中 / 已确认】
编写人：【姓名 / 部门】
审批人：【姓名 / 部门】
目录
- 模块概述
- 接口设计
- 数据设计
- 业务逻辑实现
- 技术选型与规范
- 配套产出清单
- 评审记录
1. 模块概述
1.1 模块定位
- 所属系统 / 子系统：【例：用户中心子系统】
- 核心功能描述：【例：负责用户注册、登录、Token 管理及账号信息维护，为订单、支付模块提供用户身份校验能力】
- 上下游依赖模块：
- 上游：【例：前端登录页、移动端注册界面】
- 下游：【例：订单模块（获取用户 ID）、支付模块（校验 Token 有效性）】
1.2 功能范围（含排除项）
| 功能项 | 描述 | 是否包含 | 备注 |
|---|
| 手机号 + 密码登录 | 支持手机号验证、密码加密比对 | 是 | - |
| 第三方登录（微信 / QQ） | 通过第三方 OAuth2.0 协议获取用户信息 | 否 | 二期迭代功能 |
| 账号密码重置 | 支持手机号验证码重置密码 | 是 | 需调用短信服务模块 |
1.3 需求映射
| 需求 ID | 需求描述 | 对应设计章节 |
|---|
| REQ-USER-001 | 支持手机号登录，响应延迟≤50ms | 4.1 核心流程 |
| REQ-USER-002 | 密码需加密存储，禁止明文 / MD5 存储 | 3.2 数据库设计 |
1.4 非功能目标
- 性能目标：【例：支持每秒 1000 次登录请求，峰值 QPS≤2000 时无超时】
- 安全目标：【例：Token 防篡改（签名校验）、密码加密（BCrypt 算法）、防 SQL 注入】
- 可用性目标：【例：模块服务可用性≥99.9%，单节点故障时自动切换至备用节点】
2. 接口设计
2.1 对外接口清单（HTTP/REST）
| 接口 ID | 接口名称 | 请求方式 | 接口路径 | 超时时间 | 功能描述 |
|---|
| USER-API-001 | 用户登录 | POST | /api/v1/user/login | 3s | 手机号 + 密码登录，返回 Token |
| USER-API-002 | 密码重置 | PUT | /api/v1/user/password | 5s | 验证码验证通过后更新密码 |
| USER-API-003 | Token 校验 | GET | /api/v1/user/token/verify | 2s | 下游模块校验 Token 有效性 |
2.2 接口详情（以 USER-API-001 为例）
2.2.1 请求参数
| 参数名 | 类型 | 是否必填 | 长度限制 | 校验规则 | 示例值 |
|---|
| phone | String | 是 | 11 位 | 匹配手机号正则：^1 [3-9]\d {9}$ | 13800138000 |
| password | String | 是 | 6-20 位 | 含字母 + 数字，无特殊符号 | Abc123456 |
| clientType | String | 否 | - | 枚举：APP/WEB/WECHAT，默认 WEB | APP |
2.2.2 响应参数（JSON 格式）
- 成功响应（HTTP 200）：
json
{"code": 200,"msg": "登录成功","data": {"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", // JWT格式，有效期2小时"userId": "100001","expireTime": "2024-12-31 23:59:59"}
}
- 失败响应（HTTP 400）：
json
{"code": 401,"msg": "手机号不存在","data": null
}
2.2.3 接口时序图
【此处插入时序图，工具：PlantUML/DrawIO，描述 “前端→登录接口→数据库→Redis 缓存” 的交互流程】
2.3 对内接口（模块内部 / 同子系统调用）
| 接口 ID | 调用方式 | 功能描述 | 参数 / 返回值说明 |
|---|
| USER-INNER-001 | 本地方法 | 密码加密（BCrypt） | 入参：明文密码；返回：加密后密码 |
| USER-INNER-002 | 本地方法 | Token 生成（JWT） | 入参：userId；返回：JWT 字符串 |
3. 数据设计
3.1 核心数据结构（Java 示例）
java
运行
// 用户登录请求DTO
public class LoginRequestDTO {@NotBlank(message = "手机号不能为空")@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式错误")private String phone;@NotBlank(message = "密码不能为空")@Size(min = 6, max = 20, message = "密码长度6-20位")private String password;private String clientType = "WEB"; // 默认值// getter/setter省略
}// 用户实体类（对应数据库表）
public class UserDO {private Long userId; // 主键，自增private String phone; // 唯一索引private String password; // BCrypt加密后存储private Integer status; // 1-正常，0-禁用private Date createTime; // 注册时间private Date updateTime; // 更新时间// getter/setter省略
}
3.2 数据库设计（MySQL）
3.2.1 表结构
| 表名 | user_info |
|---|
| 存储引擎 | InnoDB |
| 字符集 | utf8mb4 |
| 主键 | user_id（BIGINT，自增，步长 1） |
| 字段名 | 数据类型 | 长度 | 约束 | 索引 | 备注 |
|---|
| user_id | BIGINT | - | NOT NULL，PRIMARY KEY | 主键索引 | 唯一用户 ID |
| phone | VARCHAR | 11 | NOT NULL，UNIQUE | 唯一索引 | 用户手机号 |
| password | VARCHAR | 60 | NOT NULL | - | BCrypt 加密后的值（固定 60 位） |
| status | TINYINT | 1 | NOT NULL，DEFAULT 1 | - | 1 - 正常，0 - 禁用 |
| create_time | DATETIME | - | NOT NULL | - | 注册时间，默认 CURRENT_TIMESTAMP |
| update_time | DATETIME | - | NOT NULL | - | 更新时间，ON UPDATE CURRENT_TIMESTAMP |
3.2.2 建表 SQL 脚本
sql
CREATE TABLE `user_info` (`user_id` bigint NOT NULL AUTO_INCREMENT COMMENT '用户ID',`phone` varchar(11) NOT NULL COMMENT '手机号',`password` varchar(60) NOT NULL COMMENT '加密密码（BCrypt）',`status` tinyint NOT NULL DEFAULT '1' COMMENT '状态：1正常，0禁用',`create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '注册时间',`update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',PRIMARY KEY (`user_id`),UNIQUE KEY `idx_phone` (`phone`) COMMENT '手机号唯一索引'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='用户信息表';
3.3 缓存设计（Redis）
| 缓存 Key 格式 | 数据类型 | 有效期 | 功能描述 | 示例值 |
|---|
| user:token:{tokenId} | String | 2 小时 | 存储 Token 对应的 userId | user:token:abc123 → "100001" |
| user:login:fail:{phone} | Hash | 1 小时 | 记录登录失败次数（防暴力破解） | user:login:fail:13800138000 → {"count":3} |
4. 业务逻辑实现
4.1 核心流程（以 “用户登录” 为例）
- 接收前端请求（LoginRequestDTO），通过 Validator 校验参数格式（手机号正则、密码长度）。
- 调用 USER-INNER-001 接口，将请求中的明文密码加密（BCrypt，无需盐值存储，算法自带）。
- 查 MySQL 用户表（user_info），根据手机号获取用户信息（UserDO）：
- 若用户不存在（UserDO 为 null），返回 code=401（手机号不存在）。
- 若用户状态为 0（禁用），返回 code=403（账号已禁用）。
- 比对 “加密后的请求密码” 与 “数据库中存储的加密密码”：
- 比对失败：更新 Redis 中 “登录失败次数”，若次数≥5，返回 code=429（频繁失败，1 小时后重试）。
- 比对成功：重置 Redis 中 “登录失败次数”，调用 USER-INNER-002 接口生成 JWT Token。
- 将 Token 存入 Redis（key=user:token:{tokenId}，有效期 2 小时），返回成功响应（含 Token、userId）。
4.2 异常处理
| 异常场景 | 处理方式 | 返回 code | 日志级别 |
|---|
| 参数校验失败（手机号格式错） | 直接返回参数错误信息 | 400 | INFO |
| 数据库连接超时 | 触发重试机制（重试 3 次，间隔 100ms），重试失败则降级至备用库 | 500 | ERROR |
| Redis 缓存不可用 | 跳过缓存步骤（不影响核心登录流程），记录警告日志 | 200 | WARN |
4.3 边界条件
| 边界场景 | 处理规则 |
|---|
| 同一手机号并发登录（≥10 次 / 秒） | 触发限流，返回 code=429（10 秒后重试） |
| Token 有效期内重复登录 | 生成新 Token，旧 Token 立即失效（删除旧 Redis 缓存） |
| 密码为空字符串 | 参数校验阶段拦截，返回 code=400（密码不能为空） |
5. 技术选型与规范
5.1 技术栈清单
| 类别 | 技术选型 | 版本 | 用途 |
|---|
| 开发框架 | Spring Boot | 2.7.10 | 接口开发、依赖管理 |
| ORM 框架 | MyBatis-Plus | 3.5.3.1 | 数据库 CRUD 操作 |
| 缓存 | Redis | 6.2.6 | 存储 Token、登录失败次数 |
| 加密算法 | BCrypt | Spring Security 自带 | 密码加密 |
| 接口文档 | Swagger/OpenAPI | 3.0.0 | 接口调试、文档生成 |
| 日志框架 | Logback | 1.2.11 | 业务日志、异常日志记录 |
5.2 编码规范
- 命名规则：接口方法名用驼峰式（如 loginByPhone），数据库表名用下划线式（user_info），常量全大写 + 下划线（如 TOKEN_EXPIRE_TIME=7200）。
- 日志规范：ERROR 级日志需包含异常栈（e.printStackTrace ()），INFO 级日志需包含关键参数（如 “登录成功，userId=100001”）。
- 代码分层：Controller（接收请求）→ Service（业务逻辑）→ DAO（数据库操作），禁止跨层调用。
5.3 性能与安全优化
- 性能优化：用户信息查询加 “手机号唯一索引”，登录成功后 Token 缓存（减少 JWT 重复生成）。
- 安全优化：接口防 SQL 注入（用 MyBatis 参数绑定，禁止字符串拼接），Token 签名密钥存在配置中心（不硬编码），密码传输用 HTTPS。
6. 配套产出清单
| 产出类型 | 名称 / 描述 | 交付格式 |
|---|
| 图形化文件 | 登录接口时序图、数据流转图 | PNG/PDF |
| 技术脚本 | user_info 表建表 SQL、Redis 初始化脚本 | SQL/TXT |
| 配置文件示例 | application.yml（数据库、Redis 配置） | YML |
| 测试用例 | 登录接口测试用例（含正常 / 异常场景） | Excel/Markdown |
7. 评审记录
| 评审日期 | 评审人员 | 评审意见 | 修改情况 |
|---|
| 2024-10-01 | 架构师：张 XX | 建议增加 Token 黑名单机制（注销时失效） | 已补充 “Token 注销流程” 至 4.1 章节 |
| 2024-10-01 | 测试负责人：李 XX | 需补充 “密码重试次数清零条件” 说明 | 已在 4.1 步骤 5 补充 “24 小时后自动清零” |
根据具体项目类型（如微服务接口 / 数据库模块 / 前端组件），可以定制一细化专属 LLD 模板？比如针对微服务场景，会额外增加 “服务注册发现配置”“熔断降级设计” 等章节，更贴合实际开发需求。
