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