yuxuanhui
91861565bb
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
4.4 KiB
4.4 KiB
前端开发规范
前端开发的总入口，覆盖目录组织、接口设计、类型定义、UI 实现与质量要求。
概述
本规范用于统一前端项目的开发方式，目标是让代码在以下几个方面保持稳定：
- 可读：目录、命名、职责边界清晰，方便快速定位代码
- 可维护：页面逻辑拆分合理，避免巨型组件和重复实现
- 可复用：公共能力与页面私有能力边界明确，减少污染
- 可演进：接口、类型、页面结构支持逐步扩展，不因小改动造成大面积返工
核心原则：
- 就近原则：只在当前页面使用的代码，放在当前页面目录下
- 分层清晰：全局公共层、页面私有层、接口层各司其职
- 命名统一：文件名、目录名、Hooks、弹窗组件遵循固定规则
- 类型明确：接口参数、返回值、组件 Props、状态值都应具备清晰类型
- 优先复用：抽公共前先确认真的复用，抽公共后保持通用而不过度设计
编码环境
- Vue / React，使用 TypeScript
- Vite、路由库（React Router / Vue Router）、Axios 等常见前端库
开发前检查清单
开始修改前端代码前，请先确认：
- 这次改动是否真的属于前端层，而不是后端或其它层
- 需求影响的是全局公共能力，还是某个页面私有能力
- 涉及接口时，参数、返回值、错误处理方式是否已经明确
- 涉及样式、主题或视觉变量时，是否优先使用
@oppein-react/design-tokens - 新增命名是否使用业务语义，而不是后端表结构或临时术语
- 是否有现成组件、Hooks、工具函数、类型定义或设计 token 可以复用
- 改动是否会影响现有页面、公共组件或既有接口调用方式
规范索引
| 规范 | 作用 | 适用场景 |
|---|---|---|
| 前端结构规范 | 约束 src 下各层目录职责、页面私有结构和命名方式 |
新建页面、重构目录、抽离公共能力前必读 |
| UI 设计规范 | 规范界面实现方式、视觉一致性和交互呈现 | 新做页面、优化样式、补充组件展示时阅读 |
| 设计变量使用规范 | 规范 @oppein-react/design-tokens 的接入、变量消费、主题切换与 UnoCSS 使用方式 |
新增样式、主题切换、替换硬编码颜色、接入 UnoCSS token 时必读 |
| 接口契约规范 | 规范前端接口文件、请求封装、错误处理和兼容性 | 新增接口、调整请求参数、封装请求工具时阅读 |
| 类型定义规范 | 规范请求参数、响应数据、页面消费模型和类型边界 | 新增类型、重构数据结构、拆分页面模型时阅读 |
| 质量规范 | 规范代码质量、拆分方式、验证要求和评审重点 | 开发中自检、提测前、收尾时阅读 |
推荐使用方式
可以把这套规范理解成一个简单流程：
- 先看
frontend-structure-guidelines.md确认代码该放全局、页面私有，还是接口层 - 涉及样式、主题和设计变量时看
design-tokens-guidelines.md和DESIGN.md确保颜色、间距、圆角、阴影、亮暗主题实现方式一致 - 涉及请求与数据时看
api-guidelines.md和dto-guidelines.md确保接口定义、类型建模、页面消费方式一致 - 涉及页面与交互时看
DESIGN.md保证页面结构、交互体验与视觉实现符合要求 - 提交前看
quality-guidelines.md做最后的质量自检与风险排查
完成前自检
完成前端改动前，至少确认以下几点：
- 目录层级是否正确，页面私有代码是否已就近放置
- 接口是否统一从约定目录导出，是否避免了页面内联请求实现
- 类型是否明确，是否避免了新增
any - 样式是否优先使用了
@oppein-react/design-tokens的语义变量或 UnoCSS token class - 页面是否拆分合理，是否把复杂逻辑从主页面组件下沉
- 公共能力是否真的具备复用价值，而不是过早抽象
- 构建是否通过，关键路径是否完成本地验证
语言要求
- 所有规范文档、注释、提交信息统一使用简体中文
- 代码中的变量名、函数名、类型名可以使用英文
- 命名应优先体现业务语义，避免使用模糊缩写与临时命名