mirror of
https://github.com/fastapiadmin/FastapiAdmin.git
synced 2026-10-13 20:51:09 +00:00
zhangtao
e44f96740f
refactor(docs): 迁移文档到src目录并优化配置 style(docs): 统一代码格式和样式 chore(docs): 移除不必要的配置文件和依赖 fix(docs): 修正锁屏对话框的翻译和占位符 feat(components): 添加ElDescriptions组件支持 perf(docs): 优化文档图片加载和缩放功能
452 lines
12 KiB
Markdown
452 lines
12 KiB
Markdown
---
|
||
outline: "deep"
|
||
title: 开发规范
|
||
---
|
||
# 开发规范
|
||
|
||
## 📚规范概述
|
||
|
||
为了保证项目代码的一致性、可读性和可维护性，FastapiAdmin 项目制定了以下开发规范。所有参与项目开发的开发者都应该遵循这些规范。
|
||
|
||
## 🎨前端开发规范
|
||
|
||
### 1. 代码风格
|
||
|
||
#### 1.1 TypeScript 规范
|
||
|
||
- 使用 TypeScript 严格模式（`"strict": true`）
|
||
- 为所有变量、函数、接口添加类型注解
|
||
- 避免使用 `any` 类型，除非确实无法确定类型
|
||
- 使用接口定义对象类型，而不是类型别名
|
||
- 使用枚举定义常量集合
|
||
- 使用 `type` 定义联合类型和交叉类型
|
||
- 使用 `as const` 断言确保类型安全
|
||
- 使用 `readonly` 修饰符保护不可变数据
|
||
- 使用 `unknown` 类型处理不确定类型的数据
|
||
|
||
#### 1.2 Vue 规范
|
||
|
||
- 使用 Composition API
|
||
- 使用 `<script setup lang="ts">` 语法
|
||
- 组件命名使用 PascalCase
|
||
- 变量和函数命名使用 camelCase
|
||
- 常量命名使用 UPPER_SNAKE_CASE
|
||
- 使用 `ref()` 定义响应式变量
|
||
- 使用 `computed()` 定义计算属性
|
||
- 使用 `watch()` 或 `watchEffect()` 监听变化
|
||
- 使用 `onMounted()`、`onUnmounted()` 等生命周期钩子
|
||
- 组件 props 使用 `defineProps()` 定义并添加类型
|
||
- 组件事件使用 `defineEmits()` 定义并添加类型
|
||
- 组件暴露的属性和方法使用 `defineExpose()` 定义
|
||
|
||
#### 1.3 CSS 规范
|
||
|
||
- 使用 UnoCSS 原子化 CSS
|
||
- 避免使用内联样式
|
||
- 使用 BEM 命名规范（如果不使用 UnoCSS）
|
||
- 类名使用 kebab-case
|
||
- 避免使用 ID 选择器
|
||
- 使用 CSS 变量管理主题
|
||
- 避免使用 `!important` 修饰符
|
||
- 使用 flexbox 布局确保跨平台一致性
|
||
- 合理使用 CSS Grid 布局
|
||
- 优化 CSS 选择器优先级
|
||
|
||
### 2. 组件开发最佳实践
|
||
|
||
- **单一职责原则**：每个组件只负责一个功能
|
||
- **props 设计**：
|
||
- 使用 `required` 和 `default` 明确 props 要求
|
||
- 为复杂 props 添加验证
|
||
- 使用 `withDefaults()` 为 props 设置默认值
|
||
- **事件设计**：
|
||
- 使用 kebab-case 命名事件
|
||
- 事件参数类型明确
|
||
- 避免在事件中传递过多参数
|
||
- **插槽设计**：
|
||
- 使用具名插槽提高可读性
|
||
- 为插槽添加默认内容
|
||
- 使用作用域插槽传递数据
|
||
- **样式设计**：
|
||
- 使用 `scoped` 样式避免冲突
|
||
- 合理使用 `:deep()` 选择器
|
||
- 避免在组件中使用全局样式
|
||
|
||
### 3. 状态管理最佳实践
|
||
|
||
- **模块化设计**：按功能模块拆分 store
|
||
- **状态定义**：
|
||
- 使用 `interface` 定义 state 类型
|
||
- 初始化所有状态
|
||
- 避免使用嵌套过深的状态结构
|
||
- **Actions 设计**：
|
||
- 处理异步操作
|
||
- 使用 try/catch 捕获错误
|
||
- 提交多个 mutations 时使用事务
|
||
- **Getters 设计**：
|
||
- 缓存计算结果
|
||
- 避免在 getters 中修改状态
|
||
- 合理使用参数化 getters
|
||
|
||
### 4. API 调用最佳实践
|
||
|
||
- **模块化管理**：按功能模块组织 API 接口
|
||
- **请求封装**：
|
||
- 统一处理请求头
|
||
- 统一处理错误
|
||
- 统一处理 loading 状态
|
||
- **响应处理**：
|
||
- 类型定义响应数据结构
|
||
- 统一处理响应状态码
|
||
- 合理处理空数据和边界情况
|
||
- **请求优化**：
|
||
- 使用防抖和节流
|
||
- 缓存频繁请求的结果
|
||
- 合理使用并发请求
|
||
|
||
### 5. 性能优化建议
|
||
|
||
- **代码分割**：使用路由懒加载和组件懒加载
|
||
- **资源优化**：
|
||
- 压缩图片和静态资源
|
||
- 使用 WebP 格式图片
|
||
- 合理使用 CDN
|
||
- **渲染优化**：
|
||
- 使用 `v-memo` 缓存计算结果
|
||
- 合理使用 `v-if` 和 `v-show`
|
||
- 避免在模板中使用复杂表达式
|
||
- **网络优化**：
|
||
- 使用 HTTP/2 或 HTTP/3
|
||
- 启用 Gzip 或 Brotli 压缩
|
||
- 合理设置缓存策略
|
||
|
||
### 6. 测试最佳实践
|
||
|
||
- **测试分层**：单元测试、集成测试、端到端测试
|
||
- **测试覆盖率**：
|
||
- 核心功能 100% 覆盖
|
||
- 复杂逻辑 80% 以上覆盖
|
||
- 简单功能 50% 以上覆盖
|
||
- **测试工具**：
|
||
- 使用 Vitest 进行单元测试
|
||
- 使用 Playwright 进行端到端测试
|
||
- 使用 Vue Test Utils 进行组件测试
|
||
|
||
### 7. 代码审查要点
|
||
|
||
- **类型安全**：检查 TypeScript 类型定义是否正确
|
||
- **代码质量**：检查代码是否简洁、清晰
|
||
- **性能问题**：检查是否存在性能瓶颈
|
||
- **安全问题**：检查是否存在安全漏洞
|
||
- **规范遵循**：检查是否遵循项目开发规范
|
||
|
||
## 🐍后端开发规范
|
||
|
||
### 1. 代码风格
|
||
|
||
#### 1.1 Python 规范
|
||
|
||
- 遵循 PEP 8 代码风格
|
||
- 使用 4 个空格缩进
|
||
- 行长度不超过 100 字符
|
||
- 函数和类之间空两行
|
||
- 方法之间空一行
|
||
- 导入语句按标准库、第三方库、本地库分组
|
||
|
||
#### 1.2 FastAPI 规范
|
||
|
||
- 使用 FastAPI 装饰器定义路由
|
||
- 使用 Pydantic 模型定义请求和响应数据
|
||
- 使用依赖注入处理认证和权限
|
||
- 使用路径参数和查询参数
|
||
- 使用 HTTPException 处理错误
|
||
- 使用 Depends 注入依赖
|
||
|
||
### 2. 目录结构
|
||
|
||
```
|
||
backend/app/
|
||
├── api/ # API 接口
|
||
├── common/ # 公共代码
|
||
├── config/ # 配置管理
|
||
├── core/ # 核心功能
|
||
├── plugin/ # 插件系统
|
||
├── scripts/ # 脚本工具
|
||
└── utils/ # 工具函数
|
||
```
|
||
|
||
### 3. 插件开发规范
|
||
|
||
- 插件目录应该以 `module_` 开头
|
||
- 插件应该包含 `controller.py`、`model.py`、`schema.py`、`service.py`、`crud.py` 等文件
|
||
- 控制器应该使用 `APIRouter` 定义路由
|
||
- 路由前缀应该与模块名对应（module_xxx -> /xxx）
|
||
- 控制器应该使用 `OperationLogRoute` 记录操作日志
|
||
- 接口应该使用 `AuthPermission` 进行权限控制
|
||
|
||
### 4. 数据库规范
|
||
|
||
- 使用 SQLAlchemy 2.0 ORM
|
||
- 使用 Alembic 进行数据库迁移
|
||
- 模型类应该继承自 `Base`
|
||
- 模型类应该定义 `__tablename__` 属性
|
||
- 字段命名应该使用 snake_case
|
||
- 表名应该使用 snake_case 复数形式
|
||
- 外键应该使用 `ForeignKey` 定义
|
||
- 关系应该使用 `relationship` 定义
|
||
|
||
### 5. 认证和权限规范
|
||
|
||
- 使用 JWT 进行身份认证
|
||
- 使用 RBAC 模型进行权限管理
|
||
- 接口应该添加权限控制装饰器
|
||
- 权限字符串格式：`module:controller:action`
|
||
- 权限应该在角色管理中配置
|
||
|
||
### 6. 错误处理规范
|
||
|
||
- 使用 `HTTPException` 处理 HTTP 错误
|
||
- 使用自定义异常处理全局错误
|
||
- 错误响应应该有统一的格式
|
||
- 错误应该记录到日志
|
||
|
||
### 7. 日志规范
|
||
|
||
- 使用 Python 标准库 `logging` 模块
|
||
- 日志级别：DEBUG、INFO、WARNING、ERROR、CRITICAL
|
||
- 日志应该包含时间、级别、模块、消息等信息
|
||
- 关键操作应该记录日志
|
||
- 错误应该记录详细信息
|
||
|
||
## 📦FastApp 移动端开发规范
|
||
|
||
### 1. 代码风格
|
||
|
||
- 遵循前端开发规范
|
||
- 使用 TypeScript 严格模式
|
||
- 使用 Vue 3 Composition API
|
||
- 使用 `<script setup lang="ts">` 语法
|
||
- 组件命名使用 PascalCase
|
||
- 变量和函数命名使用 camelCase
|
||
|
||
### 2. 目录结构
|
||
|
||
```
|
||
FastApp/src/
|
||
├── api/ # API 接口
|
||
├── components/ # 组件
|
||
├── composables/ # 组合式函数
|
||
├── constants/ # 常量定义
|
||
├── enums/ # 枚举定义
|
||
├── layouts/ # 布局组件
|
||
├── pages/ # 页面文件
|
||
├── router/ # 路由配置
|
||
├── static/ # 静态资源
|
||
├── store/ # 状态管理
|
||
├── styles/ # 样式文件
|
||
├── types/ # TypeScript 类型定义
|
||
├── utils/ # 工具函数
|
||
├── App.vue # 应用根组件
|
||
└── main.ts # 应用入口文件
|
||
```
|
||
|
||
### 3. 页面开发规范
|
||
|
||
- 页面组件应该放在 `pages` 目录下
|
||
- 页面目录应该使用 kebab-case
|
||
- 页面组件应该包含 `index.vue` 文件
|
||
- 页面组件可以包含 `data.ts`、`types.ts` 等辅助文件
|
||
- 页面组件应该使用 `onLoad()`、`onShow()` 等生命周期钩子
|
||
- 页面跳转应该使用 `uni.navigateTo()`、`uni.switchTab()` 等 API
|
||
|
||
### 4. API 调用规范
|
||
|
||
- 遵循前端 API 调用规范
|
||
- 使用封装的 `request.ts` 工具
|
||
- API 接口应该按模块分类
|
||
- API 调用应该处理错误情况
|
||
- API 调用应该显示加载状态
|
||
|
||
### 5. 跨平台适配规范
|
||
|
||
- 使用条件编译处理平台差异
|
||
- 使用 `#ifdef`、`#ifndef`、`#endif` 指令
|
||
- 平台特有 API 应该添加条件编译
|
||
- 样式应该考虑不同平台的差异
|
||
- 布局应该使用 flexbox 确保跨平台一致性
|
||
|
||
## 🎯Git 提交规范
|
||
|
||
### 1. 分支管理
|
||
|
||
- `master`：主分支，用于发布生产版本
|
||
- `dev`：开发分支，用于集成开发
|
||
- `feature/xxx`：功能分支，用于开发新功能
|
||
- `bugfix/xxx`：修复分支，用于修复 bug
|
||
- `hotfix/xxx`：热修复分支，用于紧急修复生产环境问题
|
||
|
||
### 2. 提交信息规范
|
||
|
||
提交信息应该遵循以下格式：
|
||
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
<body>
|
||
|
||
<footer>
|
||
```
|
||
|
||
#### 2.1 Type
|
||
|
||
- `feat`：新功能
|
||
- `fix`：修复 bug
|
||
- `docs`：文档修改
|
||
- `style`：代码风格修改
|
||
- `refactor`：代码重构
|
||
- `test`：测试代码修改
|
||
- `chore`：构建工具或依赖修改
|
||
- `revert`：回滚提交
|
||
|
||
#### 2.2 Scope
|
||
|
||
- 可选，用于指定修改的范围
|
||
- 例如：`api`、`component`、`page`、`store` 等
|
||
|
||
#### 2.3 Subject
|
||
|
||
- 简短的提交信息，不超过 50 个字符
|
||
- 使用祈使句，动词开头
|
||
- 首字母小写
|
||
- 不需要句号结尾
|
||
|
||
#### 2.4 Body
|
||
|
||
- 可选，详细的提交信息
|
||
- 每行不超过 72 个字符
|
||
- 解释为什么修改，而不是如何修改
|
||
|
||
#### 2.5 Footer
|
||
|
||
- 可选，用于引用 issue 或 BUG
|
||
- 例如：`Closes #123`、`Fixes #456`
|
||
|
||
### 3. 提交示例
|
||
|
||
```
|
||
feat(api): 添加用户登录接口
|
||
|
||
- 实现用户登录功能
|
||
- 添加 JWT 认证
|
||
- 处理登录错误情况
|
||
|
||
Closes #123
|
||
```
|
||
|
||
```
|
||
fix(frontend): 修复首页轮播图显示问题
|
||
|
||
- 修复轮播图高度计算错误
|
||
- 优化轮播图切换动画
|
||
|
||
Fixes #456
|
||
```
|
||
|
||
```
|
||
docs: 更新开发文档
|
||
|
||
- 添加 API 文档说明
|
||
- 完善部署指南
|
||
```
|
||
|
||
### 4. Pull Request 规范
|
||
|
||
- Pull Request 应该从功能分支合并到 dev 分支
|
||
- Pull Request 标题应该清晰、语义化
|
||
- Pull Request 描述应该详细说明修改内容
|
||
- Pull Request 应该包含相关的 issue 链接
|
||
- Pull Request 应该通过所有测试
|
||
- Pull Request 应该由至少一个 reviewer 审核
|
||
|
||
## 🔧工具链规范
|
||
|
||
### 1. 前端工具链
|
||
|
||
- 使用 Vite 作为构建工具
|
||
- 使用 ESLint 进行代码检查
|
||
- 使用 Prettier 进行代码格式化
|
||
- 使用 Stylelint 进行样式检查
|
||
- 使用 Husky 进行 Git 钩子管理
|
||
- 使用 Commitlint 进行提交信息检查
|
||
|
||
### 2. 后端工具链
|
||
|
||
- 使用 Poetry 或 pip 管理依赖
|
||
- 使用 Pylint 或 Flake8 进行代码检查
|
||
- 使用 Black 进行代码格式化
|
||
- 使用 MyPy 进行类型检查
|
||
- 使用 pytest 进行测试
|
||
|
||
## 💡开发流程规范
|
||
|
||
### 1. 需求分析
|
||
|
||
- 明确功能需求
|
||
- 分析业务逻辑
|
||
- 确定技术方案
|
||
|
||
### 2. 设计阶段
|
||
|
||
- 设计数据库表结构
|
||
- 设计 API 接口
|
||
- 设计前端页面
|
||
- 设计组件结构
|
||
|
||
### 3. 开发阶段
|
||
|
||
- 创建分支
|
||
- 实现功能
|
||
- 编写测试
|
||
- 运行测试
|
||
|
||
### 4. 测试阶段
|
||
|
||
- 单元测试
|
||
- 集成测试
|
||
- 端到端测试
|
||
- 性能测试
|
||
|
||
### 5. 部署阶段
|
||
|
||
- 构建生产版本
|
||
- 部署到测试环境
|
||
- 进行回归测试
|
||
- 部署到生产环境
|
||
|
||
### 6. 维护阶段
|
||
|
||
- 监控系统运行状态
|
||
- 处理 bug 和问题
|
||
- 进行性能优化
|
||
- 进行功能迭代
|
||
|
||
## 📚参考资料
|
||
|
||
- [TypeScript 官方文档](https://www.typescriptlang.org/docs/)
|
||
- [Vue 官方文档](https://vuejs.org/docs/)
|
||
- [FastAPI 官方文档](https://fastapi.tiangolo.com/)
|
||
- [SQLAlchemy 官方文档](https://docs.sqlalchemy.org/)
|
||
- [PEP 8 代码风格指南](https://peps.python.org/pep-0008/)
|
||
- [Conventional Commits](https://www.conventionalcommits.org/)
|
||
- [ESLint 官方文档](https://eslint.org/docs/)
|
||
- [Prettier 官方文档](https://prettier.io/docs/en/)
|
||
|
||
## 🤝贡献指南
|
||
|
||
如果您对开发规范有任何建议或改进意见，欢迎提交 Issue 或 Pull Request。我们会认真考虑每一个建议，不断完善开发规范。
|
||
|
||
## 📄许可协议
|
||
|
||
本开发规范文档采用 MIT 许可协议，与 FastapiAdmin 项目保持一致。
|
||
|