7.6 KiB
电商订单管理系统 — 工程规范文档
本文档由订单研发团队维护，最后更新于 2026 年 7 月。
项目背景
本项目是一个面向 B 端商家的电商订单管理系统，日均订单量约 50 万单。系统采用微服务架构，包含订单服务、支付服务、库存服务和物流服务四个核心模块。
技术栈：
- 后端：Java 17 + Spring Boot 3.2 + MyBatis-Plus
- 前端：React 18 + TypeScript 5.3 + Vite
- 数据库：MySQL 8.0 + Redis 7
- 消息队列：RocketMQ 5.x
团队介绍
订单研发团队目前有 12 人：
- 后端 6 人（含 1 名 Tech Lead）
- 前端 3 人
- QA 2 人
- DevOps 1 人
团队代码仓库：[email protected]:order-team/oms.git
一、安全相关规范
在 2026 Q2 的安全审计中，我们发现线上代码中存在硬编码的数据库密码，导致一次严重的安全事件。因此制定以下规范：
1.1 禁止硬编码凭证
severity: error 适用语言：JavaScript、TypeScript、Java
禁止在源码中硬编码密码、令牌、API Key 等敏感凭证。检测到疑似硬编码凭证时，请使用环境变量或密钥管理服务注入。
以下是一个反面示例（请勿模仿）：
// ❌ 错误做法
public class DatabaseConfig {
private String password = "Admin@123456";
private String apiKey = "sk-abc123xyz";
}
// ✅ 正确做法
public class DatabaseConfig {
@Value("${db.password}")
private String password;
@Value("${api.key}")
private String apiKey;
}
1.2 禁止使用 eval()
severity: error 适用语言：JavaScript、TypeScript
上周代码审查中发现前端模块有 eval() 调用，存在代码注入风险。eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代。
// ❌ 错误：使用 eval 解析用户输入
const data = eval(request.body);
// ✅ 正确：使用 JSON.parse
const data = JSON.parse(request.body);
1.3 禁止直接赋值 innerHTML
severity: warning
这是一条通用规则，适用于所有语言（因为各端都可能涉及 DOM 操作）。避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗。
相关讨论参见 内部 Wiki: XSS 防护指南
二、命名规范
以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide，根据团队实际情况做了调整。
2.1 常量命名
severity: warning 适用语言：JavaScript、TypeScript、Java
常量命名必须使用全大写加下划线（SCREAMING_SNAKE_CASE）。常量应使用全大写命名，如 MAX_RETRY_COUNT。
// ❌ 错误
static final int maxRetry = 3;
static final String DbHost = "localhost";
// ✅ 正确
static final int MAX_RETRY = 3;
static final String DB_HOST = "localhost";
2.2 布尔变量前缀
severity: info 适用语言：JavaScript、TypeScript
布尔变量和方法名应以 is/has/can/should 开头。布尔变量建议添加 is/has/can/should 前缀以提升可读性。
// ❌ 错误
let active = true;
let user = { verified: true };
function check(): boolean { ... }
// ✅ 正确
let isActive = true;
let user = { isVerified: true };
function canCheck(): boolean { ... }
三、性能规范
架构说明
订单服务采用 CQRS 模式，写操作走主库，读操作走从库。在高并发场景下，以下性能规范尤为重要。
3.1 禁止深层嵌套循环
severity: warning 适用语言：JavaScript、TypeScript、Java
禁止三层及以上嵌套循环，时间复杂度过高。检测到深层嵌套循环（≥3层）时，建议重构为扁平结构或使用查找表优化。
// ❌ 错误：O(n³) 的订单匹配逻辑
for (const order of orders) {
for (const item of order.items) {
for (const warehouse of warehouses) {
// 匹配逻辑...
}
}
}
// ✅ 正确：使用 Map 优化为 O(n)
const warehouseMap = new Map(warehouses.map(w => [w.id, w]));
for (const order of orders) {
for (const item of order.items) {
const wh = warehouseMap.get(item.warehouseId);
}
}
3.2 异步函数内禁止同步 API
severity: warning 适用语言：JavaScript、TypeScript
异步函数内禁止调用同步阻塞 API。在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本。
2026-07-15 会议纪要
- 讨论了 Node.js 事件循环阻塞问题
- 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API
- 下个 Sprint 开始 Code Review 时执行
四、代码风格
4.1 函数显式类型注解
severity: info 适用语言：TypeScript
函数参数和返回值应显式标注 TypeScript 类型。建议为函数添加显式类型注解，提升类型安全性。
// ❌ 错误
function createOrder(data) {
return api.post('/orders', data);
}
// ✅ 正确
function createOrder(data: CreateOrderDTO): Promise<OrderResponse> {
return api.post('/orders', data);
}
4.2 禁止魔法数字
severity: info 适用语言：JavaScript、TypeScript
禁止在代码中直接使用魔法数字，应提取为命名常量。检测到魔法数字，建议提取为具名常量以提升可维护性。
// ❌ 错误
if (order.status === 3) { ... }
setTimeout(retry, 5000);
// ✅ 正确
const ORDER_STATUS_SHIPPED = 3;
const RETRY_DELAY_MS = 5000;
if (order.status === ORDER_STATUS_SHIPPED) { ... }
setTimeout(retry, RETRY_DELAY_MS);
五、团队约定
部署流程说明
部署流程参考 CI/CD Pipeline 文档。每周二、四发布，发布窗口为 14:00-16:00。
5.1 throw 语句携带上下文
severity: warning 适用语言：JavaScript、TypeScript、Java
throw 语句必须携带错误上下文信息。throw 时应提供足够的上下文信息，便于问题定位。
// ❌ 错误
throw new RuntimeException("失败");
throw new Error("error");
// ✅ 正确
throw new OrderNotFoundException("订单不存在, orderId=" + orderId);
throw new PaymentFailedException("支付失败", cause);
5.2 禁止遗留 TODO 注释
severity: info 排除语言：SQL
生产代码中不应遗留 TODO/FIXME/HACK 注释。代码中发现 TODO/FIXME/HACK 注释，请在发布前处理。
注：SQL 脚本中允许临时性的 TODO 标记，因为数据库迁移脚本的生命周期与代码不同。
5.3 公共函数文档注释
severity: info 适用语言：JavaScript、TypeScript、Java
公共函数应添加文档注释（JSDoc / Javadoc）。公共函数缺少文档注释，建议补充说明用途、参数和返回值。
/**
* 创建订单
* @param request 订单创建请求
* @return 订单创建结果
* @throws InsufficientStockException 库存不足时抛出
*/
public OrderResult createOrder(CreateOrderRequest request) { ... }
/**
* 获取用户订单列表
* @param userId 用户ID
* @param page 分页参数
* @returns 订单列表
*/
function getUserOrders(userId: string, page: Pagination): Promise<Order[]> { ... }
附录
A. 代码审查 Checklist
- 安全规范是否遵守
- 命名规范是否一致
- 性能是否有明显瓶颈
- 代码风格是否统一
- 团队约定是否遵循
B. 相关链接
C. 版本历史
| 版本 | 日期 | 作者 | 变更说明 |
|---|---|---|---|
| 1.0 | 2026-06-01 | 张三 | 初版 |
| 1.1 | 2026-07-15 | 李四 | 新增性能规范 |
| 1.2 | 2026-08-01 | 王五 | 补充代码示例 |