电商订单管理系统 — 工程规范文档 团队：订单研发团队（后端6人 + 前端3人 + QA2人 + DevOps1人） 最后更新：2026-07-15 仓库：git@company.com:order-team/oms.git ================================================================================ 项目背景 ================================================================================ 本项目是一个面向 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 人 团队代码仓库：git@company.com:order-team/oms.git 内部 Wiki：https://wiki.internal/order-team ================================================================================ 一、安全相关规范 ================================================================================ 在 2026 Q2 的安全审计中，我们发现线上代码中存在硬编码的数据库密码， 导致一次严重的安全事件。因此制定以下规范： ---- 规则 ---- 名称：禁止硬编码凭证 严重级别：error 适用语言：javascript, typescript, java 描述：禁止在源码中硬编码密码、令牌、API Key 等敏感凭证 提示：检测到疑似硬编码凭证，请使用环境变量或密钥管理服务注入 以下是反面示例（请勿模仿）： // Java: 硬编码密码 public class DatabaseConfig { private String password = "Admin@123456"; private String apiKey = "sk-abc123xyz"; } // JavaScript: 硬编码 Token const API_TOKEN = "ghp_abc123def456"; 正确做法： @Value("${db.password}") private String password; const apiToken = process.env.API_TOKEN; ---- 规则 ---- 名称：禁止使用 eval() 严重级别：error 适用语言：javascript, typescript 描述：禁止使用 eval() 函数，存在代码注入风险 提示：eval() 存在安全风险，请使用 JSON.parse() 或 Function 构造器替代 上周代码审查中发现前端模块有 eval() 调用： // 错误：使用 eval 解析用户输入 const data = eval(request.body); // 正确：使用 JSON.parse const data = JSON.parse(request.body); ---- 规则 ---- 名称：禁止直接赋值 innerHTML 严重级别：warning 适用语言：所有语言 描述：禁止直接赋值 innerHTML，可能导致 XSS 提示：避免直接操作 innerHTML，请使用 textContent 或 DOMPurify 清洗 相关讨论参见内部 Wiki: XSS 防护指南 ================================================================================ 二、命名规范 ================================================================================ 以下命名规范参考了 Google Java Style Guide 和 Airbnb JavaScript Style Guide， 根据团队实际情况做了调整。 ---- 规则 ---- 名称：常量使用全大写命名 严重级别：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"; ---- 规则 ---- 名称：布尔变量添加前缀 严重级别：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 模式，写操作走主库，读操作走从库。 在高并发场景下，以下性能规范尤为重要。 ---- 规则 ---- 名称：禁止三层以上嵌套循环 严重级别：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); } } ---- 规则 ---- 名称：异步函数内禁止同步 API 严重级别：warning 适用语言：javascript, typescript 描述：异步函数内禁止调用同步阻塞 API 提示：在 async 函数中调用同步 API 会阻塞事件循环，请改用异步版本 --- 2026-07-15 会议纪要 --- - 讨论了 Node.js 事件循环阻塞问题 - 决定在 async 函数中全面禁用 fs.readFileSync 等同步 API - 下个 Sprint 开始 Code Review 时执行 - 张三负责更新 ESLint 配置 - 李四负责前端代码排查 ================================================================================ 四、代码风格 ================================================================================ ---- 规则 ---- 名称：函数显式类型注解 严重级别：info 适用语言：typescript 描述：函数参数和返回值应显式标注 TypeScript 类型 提示：建议为函数添加显式类型注解，提升类型安全性 // 错误 function createOrder(data) { return api.post('/orders', data); } // 正确 function createOrder(data: CreateOrderDTO): Promise { return api.post('/orders', data); } ---- 规则 ---- 名称：禁止魔法数字 严重级别：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); ================================================================================ 五、团队约定 ================================================================================ 部署流程说明： 每周二、四发布，发布窗口 14:00-16:00。 CI/CD Pipeline 详见 Jenkins 配置。 ---- 规则 ---- 名称：throw 语句携带上下文 严重级别：warning 适用语言：javascript, typescript, java 描述：throw 语句必须携带错误上下文信息 提示：throw 时应提供足够的上下文信息，便于问题定位 // 错误 throw new RuntimeException("失败"); throw new Error("error"); // 正确 throw new OrderNotFoundException("订单不存在, orderId=" + orderId); throw new PaymentFailedException("支付失败", cause); ---- 规则 ---- 名称：禁止遗留 TODO 注释 严重级别：info 排除语言：sql 描述：生产代码中不应遗留 TODO/FIXME/HACK 注释 提示：代码中发现 TODO/FIXME/HACK 注释，请在发布前处理 注：SQL 脚本中允许临时性的 TODO 标记，因为数据库迁移脚本的生命周期与代码不同。 ---- 规则 ---- 名称：公共函数文档注释 严重级别：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 { ... } ================================================================================ 附录 ================================================================================ A. 代码审查 Checklist [ ] 安全规范是否遵守 [ ] 命名规范是否一致 [ ] 性能是否有明显瓶颈 [ ] 代码风格是否统一 [ ] 团队约定是否遵循 B. 相关链接 - Google Java Style Guide: https://google.github.io/styleguide/javaguide.html - Airbnb JavaScript Style Guide: https://github.com/airbnb/javascript - TypeScript ESLint Rules: https://typescript-eslint.io/rules/ C. 版本历史 v1.0 2026-06-01 张三 初版 v1.1 2026-07-15 李四 新增性能规范 v1.2 2026-08-01 王五 补充代码示例