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 请求，参数校验，调用 service，返回统一响应
service	业务逻辑编排，事务边界；接口与实现分离
mapper	数据访问层（MyBatis-Plus），单表 CRUD + 自定义 SQL
entity	与表 1:1 映射的 PO
dto	入参对象（接口入参）
vo	出参对象（接口响应）

1.2 命名约定

• 包名：全小写，根包 com.xly.erp，子包按业务模块代码小写（如 module.usr）
• 类名：UpperCamelCase；Controller 后缀 Controller，Service 接口无后缀、实现类后缀 Impl，Mapper 后缀 Mapper，实体后缀 Entity 可省略
• 方法名：lowerCamelCase；CRUD 动词：create / update / removeById / getById / page / list
• 常量：全大写下划线，如 MAX_LOGIN_ATTEMPTS

示例 1：com.example.erp.module.usr.controller.UserController 示例 2：com.example.erp.module.mod.service.impl.ModuleServiceImpl

1.3 统一响应格式

所有接口返回 Result<T>：

// 成功
{ "code": 0, "msg": "ok", "data": { /* 业务数据 */ } }
// 失败
{ "code": 40001, "msg": "用户名或密码错误", "data": null }

错误码段位划分：

• 0：成功
• 1xxxx：参数校验失败
• 2xxxx：认证 / 鉴权失败
• 3xxxx：业务规则失败
• 5xxxx：系统内部错误

1.4 异常处理

• 全局 @RestControllerAdvice 拦截所有 Controller 抛出的异常
• 业务异常用自定义 BizException(code, msg)，由全局处理器转为标准 Result
• 参数校验异常（MethodArgumentNotValidException）统一返回 1xxxx 错误码
• 接口响应禁止回显后端异常堆栈——返回用户友好错误码 + 文案，堆栈只记日志
• 不要在 controller / service 里 catch 后吞异常，必须向上抛或显式转 BizException

1.5 事务

• 事务边界统一在 service 实现类，使用 @Transactional(rollbackFor = Exception.class)
• controller / mapper 层禁止开事务
• 跨服务调用（远程 RPC / HTTP）禁止包在事务里；如需保证最终一致性走消息或补偿，不依赖数据库事务

1.6 认证

• 登录使用用户名 + 密码，后端签发 JWT（HS256），写入响应 body
• Token 生命周期：access token 8 小时；引入 refresh token（30 天）支持刷新
• 密钥放 .env.local 的 JWT_SECRET，禁止入仓
• 受保护接口由 Spring Security JwtAuthenticationFilter 校验；未携带或过期返回 2xxxx

二、前端规范

2.1 目录约定

目录	职责
api/	HTTP 请求封装；每模块一文件；前端禁止直接写 SQL / 操作 DB，所有数据访问走此层
components/	通用展示组件（无业务语义）
pages/	按模块分子目录，每 REQ 一页面
store/	Redux Toolkit slices；只放跨页面共享状态
hooks/	自定义 hooks，如 useUser / usePagination
utils/	工具函数（日期、金额、权限）
router/	路由配置

2.2 状态管理

• 服务端数据：每个页面独立请求 + 局部 useState，不进 Redux
• 跨页面共享：登录用户、权限、模块树 等放 Redux Toolkit
• 表单状态：使用 Ant Design Form.useForm，不进 Redux

2.3 请求封装

• 统一 axios 实例，配置：baseURL=/api、超时 15s、自动注入 Authorization: Bearer <token>
• 响应拦截器：code !== 0 触发统一错误处理（message.error(msg) + 抛错），401 跳登录
• 不在业务代码里手动设置请求头

2.4 错误处理

• 网络错误：拦截器统一 message.error('网络异常')
• 业务错误（code !== 0）：拦截器读 msg 字段提示，业务代码可 catch 自定义补充
• 页面级错误（路由错误 / 渲染异常）：ErrorBoundary 包裹，展示 Result 组件

三、共同约定

3.1 Git 提交

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

业务类（feat / fix / test）必须带 REQ-XXX-NNN 后缀。

3.2 分页查询

• 后端：使用 MyBatis-Plus Page<T>，请求入参 pageNum（1 起）+ pageSize（默认 20，上限 100）；响应 { records, total, pageNum, pageSize }
• 前端：Table 配 pagination 配置，与后端字段一一对应

3.3 日期与金额

• 后端：日期统一 LocalDateTime（无时区业务）/ OffsetDateTime（有时区）；金额一律 BigDecimal，小数位精度由业务规则决定
• 前端：日期展示用 dayjs，统一格式 YYYY-MM-DD HH:mm:ss；金额展示保留 2 位小数 + 千分位

3.4 数据访问规约

• SELECT 字段必须显式列举，禁止 SELECT *
• 循环中禁止执行 DB 查询（N+1 反模式），改用批量 IN / JOIN / 一次查 Map 建索引
• Mapper XML 字段名 / 表名通过 <sql> 片段或常量引用，避免散落字符串
• 复杂查询用 MyBatis-Plus LambdaQueryWrapper；动态 SQL 用 XML

3.5 配置与安全

• DB 连接 / Redis 地址 / JWT 密钥 / 第三方 URL 一律放 application.yml + .env.local，代码里禁止硬编码
• 前端 localStorage 禁止存敏感信息（token / 身份证 / 个人数据），token 存内存 + refresh token 走 HttpOnly Cookie
• 接口响应禁止回显异常堆栈（与 § 1.4 一致）