04-技术规范

零、技术栈总览

分层模块	技术	版本要求	说明
前端基础框架	React	18.x	构建前端应用
前端 UI 组件	Ant Design	5.x	页面组件与交互控件
前端状态管理	Redux Toolkit	最新稳定版	管理全局状态
前端路由管理	React Router	v6	页面路由与导航
前端工程化构建	Vite	最新稳定版	前端开发与打包构建
前端接口通信	Axios	最新稳定版	调用后端 API
后端基础框架	Spring Boot	3.x	构建后端服务
后端数据访问	MyBatis-Plus	最新稳定版	数据库访问与 ORM 增强
工作流引擎	Activiti	6.x	审批流、流程流转
缓存服务	Redis	最新稳定版	缓存、会话、分布式能力
报表打印	JXLS	2.8.1	基于 Excel 模板生成报表
Excel 导入导出	EasyExcel	4.0.3	Excel 数据导入导出
关系型数据库	MySQL	8.x	核心业务数据存储
数据库 schema 迁移	Flyway (flyway-core + flyway-mysql)	10.x / 最新稳定版	sql/migrations/V_n__*.sql 顺序 apply；Spring Boot 启动时自动应用
接口风格	RESTful API	统一规范	前后端接口设计规范
权限认证	Spring Security / JWT	最新稳定版	登录认证、权限控制
API 文档	OpenAPI / Swagger	最新稳定版	接口文档与调试
项目构建管理	Maven	3.9.x	Java 项目依赖与构建
JDK 运行环境	Java	17 / 21	Spring Boot 3 推荐版本
部署容器	Docker	最新稳定版	容器化部署
Web 服务器 / 反向代理	Nginx	最新稳定版	前端托管、反向代理、负载分发
日志管理	Logback	默认集成 / 最新稳定版	应用日志输出
对象映射工具	MapStruct	最新稳定版	DTO / VO / Entity 转换
工具类库	Hutool / Apache Commons	最新稳定版	常用工具方法支持

本表由 scope-lock 锁定。后续所有规范基于此表推导。

一、后端规范

1.1 分层结构

层	职责
controller	解析 HTTP 入参 / 校验请求体格式 / 返回 Result<T>；不写业务逻辑
service	业务流程编排、事务边界、跨 Mapper 组合；接口 + impl 拆开
mapper	数据访问，对应一张表；XML 写 SQL，禁止跨表 JOIN 之外的业务判断
entity	与数据库表一一映射的 PO；不带业务方法
dto / vo	入参（DTO） / 出参（VO）专用结构；通过 MapStruct 与 entity 转换
common	跨模块基础设施（异常 / 响应 / 配置 / 工具 / 安全）

调用方向严格自上而下，禁止反向依赖（Controller 不能被 Service import）。

1.2 命名约定

• 包名：根包com.xly.test4，全小写点分隔；模块代码小写作为子包（USR → usr）。
• 类名：大驼峰，按职责加后缀：UserController / UserService / UserServiceImpl / UserMapper / UserCreateDTO / UserVO。
• 方法名 / 变量：小驼峰；布尔以 is / has / can 开头。
• 常量：UPPER_SNAKE_CASE，定义在 common.constant.<Module>Constants。

示例：

// 示例 1：Controller
@RestController
@RequestMapping("/api/usr/user")
public class UserController {
    public Result<Long> createUser(@Valid @RequestBody UserCreateDTO dto) { ... }
}

// 示例 2：常量
public final class UserConstants {
    public static final int MAX_LOGIN_FAIL_TIMES = 5;
}

1.3 统一响应格式

所有 Controller 返回 Result<T>，结构：

// 成功
{ "code": "0", "msg": "ok", "data": { ... }, "traceId": "..." }

// 失败
{ "code": "USR-001", "msg": "用户名已存在", "data": null, "traceId": "..." }

错误码段位：

段位	含义
0	成功
1xxx	通用框架错误（参数校验失败、权限不足、未登录）
<MOD>-<NNN>	业务错误，MOD 与模块代码一致（如 USR-001）
5xxx	系统内部错误（DB 异常、第三方调用失败）

1.4 异常处理

• 使用 @RestControllerAdvice 全局异常处理器，统一捕获并转 Result.fail(...)。
• 业务异常用自定义 BusinessException(code, msg) 抛出，不要 catch 后吞掉。
• 参数校验异常（MethodArgumentNotValidException）→ 1001 + 首个字段错误信息。
• 未预期异常 → 5000 + 通用文案"系统繁忙，请稍后重试"；接口响应禁止回显堆栈，堆栈只进 Logback。
• traceId 在 Filter 层注入 MDC，错误响应中回填便于排查。

1.5 事务

• @Transactional 仅打在 Service 实现类方法上，默认 rollbackFor = Exception.class。
• Controller 层禁止打事务注解。
• 一个 Service 方法只能跨当前模块的 Mapper；调用另一模块必须走对方 Service 的公共方法。
• 跨服务（跨进程）调用 禁止包在事务里；如有最终一致性需求走异步 + 补偿。

1.6 认证

• 使用 Spring Security + JWT；登录接口签发 accessToken（24h）+ refreshToken（7 天）。
• token 放 Authorization header，格式 Bearer <token>。
• 密钥从 .env.local → JWT_SECRET 注入到 application.yml，代码里禁止硬编码。
• 刷新机制：accessToken 过期前 30 分钟前端用 refreshToken 换新；refreshToken 一次性使用，签发新 access 时同时滚动新 refresh。

二、前端规范

2.1 目录约定

目录	职责
api/	后端接口封装；每模块一文件；导出函数对应 REQ 接口
components/	跨页面通用组件；无业务耦合
pages/	业务页面；按模块代码分子目录
store/	Redux Toolkit slice；按模块拆分
hooks/	自定义 hooks
utils/	纯函数工具（日期、金额、字符串等）
styles/	全局样式 + Design Tokens

前端禁止直接写 SQL / 操作 DB / 直连数据库连接；所有数据访问走 api/ 层 axios 封装。

2.2 状态管理

• 服务端数据：默认不存 Redux；通过 useQuery 风格 hook 或就近 useState + useEffect 拉取；如确实需跨页面共享（如当前用户信息），存 store/ 对应 slice。
• 全局状态：登录态、当前用户、权限列表、菜单 → Redux。
• 页面级状态：表单字段、过滤条件、分页 → useState 或 useReducer，不进 Redux。

2.3 请求封装

• 单例 axios 实例，baseURL 由环境变量注入。
• 请求拦截器：从 Redux 取 accessToken 注入 Authorization header。
• 响应拦截器：
  • code === '0' → resolve data
  • 401 → 自动调 refresh 接口尝试续期；失败则清空登录态跳 /login
  • 其他失败 → reject Result，由调用方决定弹窗
• 默认超时 15s；GET 类请求允许业务侧覆盖至 60s（如导出大数据量列表）。
• 重试：默认不重试；幂等查询接口（GET）业务侧可显式配置 1 次重试。

2.4 错误处理

• 网络错误（无 response）：响应拦截器统一 notification.error「网络异常，请检查连接」。
• 业务错误（code !== '0'）：reject 给调用方；调用方根据场景决定 message.error（inline）或 notification.error（异步任务）。
• 页面级错误（路由懒加载失败 / 组件渲染异常）：用 React ErrorBoundary 兜底，展示 Result 错误页 + "重试"按钮。

2.5 样式与主题

• CSS 变量命名格式：--color-<scope>-<role>-<state>
  • <scope>：form / table-row / button / 其他组件域名
  • <role>：bg / fg / border
  • <state>：edit / readonly / hover / selected / disabled
• 文件位置：src/styles/tokens.css，由 skeleton-gen 生成空骨架，色值由 docs/06 § 二锁定后填入。
• 组件样式中只允许 var(--color-xxx)，禁止硬编码 hex / rgba。
• 与 Ant Design 5 对接：在 App 根层用 ConfigProvider，将 token 值绑定到 theme.token.colorPrimary 等。
• 具体 token 表见 docs/06 § 二。

三、共同约定

3.1 Git 提交

<type>(<scope>): <subject> REQ-XXX-NNN

具体规则见 CLAUDE.md § 🗂️ Git 提交规范。

3.2 分页查询

• 后端入参：PageQuery { pageNum: int=1, pageSize: int=20, ... }，pageSize 上限 100。
• 后端出参：PageResult<T> { records: List<T>, total: long, pageNum: int, pageSize: int }。
• 前端：Ant Design Table + pagination 双向绑定 pageNum / pageSize；切换时清空选中行。
• 排序与过滤条件并入 PageQuery 子类（如 UserPageQuery），避免接口爆炸。

3.3 日期与金额

• 后端类型：日期一律 LocalDateTime（含时分秒）或 LocalDate（仅日期）；JSON 序列化用 ISO-8601 字符串（yyyy-MM-dd'T'HH:mm:ss）。
• 金额类型：BigDecimal，标度（scale）= 2（保留 2 位小数），所有运算用 BigDecimal.divide(..., RoundingMode.HALF_UP) 避免 double 精度丢失。
• 前端展示：
  • 日期用 dayjs 统一格式化，列表 YYYY-MM-DD HH:mm，详情 YYYY-MM-DD HH:mm:ss。
  • 金额展示用千分位 + 2 位小数；展示前必须 Number.toFixed(2)。

3.4 数据访问规约

• SELECT 字段必须显式列举，禁止 SELECT *；新增字段时同步更新 Mapper XML 与 entity。
• 禁止循环中执行 DB 查询（N+1 反模式）；改用：
  • 批量查询：Mapper.selectBatchIds(ids)
  • IN 子句：Mapper.selectByIds(ids) 一次拉取
  • JOIN：在 XML 内 JOIN 子表
• Mapper XML 内字段与表名建议用 <sql> 复用片段或常量；禁止字符串拼接 SQL 片段。
• MyBatis-Plus 的 LambdaQueryWrapper 优先于硬编码字符串列名。

3.5 配置与安全

• 配置外置：DB 连接 / 端口 / 密钥 / 第三方 URL 等一律放 application.yml + .env.local；
  • application.yml 写占位 ${JWT_SECRET}
  • 真实值放 .env.local（不入 git）
  • 代码里禁止硬编码任何凭据。
• 前端安全：
  • localStorage 不存敏感信息（token / 身份 / 个人数据）。
  • 推荐 HttpOnly Cookie 存 refreshToken；accessToken 放内存（Redux）+ 刷新机制兜底。
  • 接口响应禁止回显后端异常堆栈（与 § 1.4 一致），错误码 + 文案足够。