前端研发规范（生产级）

健康生活 2025年09月07日 11:42 1 admin

我帮你把刚才优化后的生产级前端研发规范整理成一份可直接放进团队仓库或知识库的 Markdown 模版，结构清晰、可执行、方便长期维护。你可以保存为 FRONTEND_GUIDELINES.md 或放到 Confluence/Wiki 中，作为团队的统一研发规范手册。

# 前端研发规范（生产级）> 版本：v1.0  > 适用范围：本规范适用于本团队所有 Web 前端项目（含 PC、移动端、跨端应用）。---## 1. 架构设计关注的核心方面### 1.1 业务目标与约束- 明确业务场景、用户规模、性能指标（首屏 ≤ 2s，交互延迟 ≤ 100ms）。- 识别非功能性需求：安全性、可维护性、可扩展性、可观测性、可测试性、可访问性（A11y）。### 1.2 团队能力与交付周期- 技术栈与团队熟悉度匹配，避免过度追新。- 考虑维护成本、招聘难度、培训成本。### 1.3 系统复杂度与演进- 预留扩展点，支持模块化、插件化、微前端。- 渐进式升级，避免大规模重构。### 1.4 生态与社区- 优先选择成熟度高、社区活跃、文档完善的技术。### 1.5 跨端适配- 明确响应式设计方案或多端适配策略。---## 2. 架构设计原则与要求1. **KISS**：能简单解决的绝不复杂化。2. **高内聚、低耦合**：模块职责单一，接口清晰。3. **渐进式增强**：兼容低版本设备，利用现代特性优化体验。4. **可观测性**：埋点、日志、性能监控、错误上报。5. **安全优先**：防御常见 Web 攻击。6. **性能优先**：按需加载、缓存策略、资源压缩、骨架屏。7. **演进性**：可平滑升级，不锁死在某个版本或技术。8. **可测试性**：架构设计需便于单元测试、集成测试。9. **可访问性**：遵循 WCAG 标准。---## 3. 领域建模（DDD 在前端的应用）### 3.1 分层与限界上下文- **领域划分**：按业务域拆分模块。- **限界上下文**：每个域有独立的状态管理、服务层、UI 组件。### 3.2 核心构件- **实体（Entity）**：有唯一标识的业务对象。- **值对象（Value Object）**：无唯一标识、不可变。- **聚合（Aggregate）**：相关实体和值对象的集合。- **领域服务（Domain Service）**：跨实体的业务逻辑。- **仓储（Repository）**：数据访问与持久化抽象。- **应用层（Application Layer）**：协调 UI 与领域逻辑。- **防腐层（ACL）**：隔离外部系统模型与内部模型。---## 4. 编码规范### 4.1 命名规范- 组件：`PascalCase`- 变量/函数：`camelCase`- 常量：`UPPER_SNAKE_CASE`### 4.2 文件结构- 按功能模块划分目录（feature-based）。- 每个模块包含：components/ # 组件 services/ # API 调用与业务服务 hooks/ # 自定义 Hook 或组合式函数 types/ # 类型定义tests/ # 测试文件### 4.3 代码风格- 缩进：统一 2 空格。- 引号：统一单引号 `'`。- 禁止魔法数字，使用常量。- 必要注释：函数、类、复杂逻辑逐行注释。### 4.4 样式规范- 使用 CSS Modules / BEM 命名。- 主题变量统一管理。### 4.5 测试规范- 单元测试、E2E 测试目录与命名统一。- 覆盖率 ≥ 80%。### 4.6 提交规范- 使用 commitlint，遵循 `feat`/`fix`/`docs`/`refactor` 等前缀。- 关联任务 ID。### 4.7 依赖管理- 锁定版本（package-lock.json / pnpm-lock.yaml）。- 定期升级与安全扫描。---## 5. 安全要求1. 防御 XSS、CSRF、SQL/NoSQL 注入。2. 敏感信息保护：脱敏显示、传输加密。3. 依赖安全扫描（npm audit / Snyk）。4. 前端权限控制与路由守卫。5. 禁止在日志中输出敏感信息。---## 6. 工程化与运维1. **CI/CD**：自动执行 Lint、Test、Build、Deploy。2. **灰度发布与回滚策略**。3. **CDN 缓存与版本管理**。4. **构建信息注入**（版本号、构建时间）。---## 7. 检查清单（落地执行）- [ ] 架构设计文档已评审通过。- [ ] 模块边界与限界上下文已定义。- [ ] ESLint + Prettier + Stylelint 配置完成。- [ ] 单元测试覆盖率 ≥ 80%。- [ ] 性能指标达标（首屏、交互延迟）。- [ ] 安全扫描通过。- [ ] CI/CD 流程跑通。- [ ] 版本信息可追溯。---> **维护说明**：本规范需每季度回顾一次，根据业务与技术演进进行更新。

前端研发规范（生产级）

我建议你把这个文件直接放到项目根目录，命名为 FRONTEND_GUIDELINES.md，并在 README 里加一行链接，确保新成员第一时间看到。
如果你愿意，我还可以帮你配一份 配套的 ESLint/Prettier/Stylelint 配置文件和 commitlint 配置，让这些规范直接在工程里自动执行，避免靠人工记忆。这样落地效果会更好。你要我帮你加上吗？