开发规范

📚规范概述

为了保证项目代码的一致性、可读性和可维护性，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 个字符
解释为什么修改，而不是如何修改

可选，用于引用 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 和问题
进行性能优化
进行功能迭代

📚参考资料

🤝贡献指南

如果您对开发规范有任何建议或改进意见，欢迎提交 Issue 或 Pull Request。我们会认真考虑每一个建议，不断完善开发规范。

📄许可协议

本开发规范文档采用 MIT 许可协议，与 FastapiAdmin 项目保持一致。

开发规范 ​

📚规范概述 ​

🎨前端开发规范 ​

1. 代码风格 ​

1.1 TypeScript 规范 ​

1.2 Vue 规范 ​

1.3 CSS 规范 ​

2. 组件开发最佳实践 ​

3. 状态管理最佳实践 ​

4. API 调用最佳实践 ​

5. 性能优化建议 ​

6. 测试最佳实践 ​

7. 代码审查要点 ​

🐍后端开发规范 ​

1. 代码风格 ​

1.1 Python 规范 ​

1.2 FastAPI 规范 ​

2. 目录结构 ​

3. 插件开发规范 ​

4. 数据库规范 ​

5. 认证和权限规范 ​

6. 错误处理规范 ​

7. 日志规范 ​

📦FastApp 移动端开发规范 ​

1. 代码风格 ​

2. 目录结构 ​

3. 页面开发规范 ​

4. API 调用规范 ​

5. 跨平台适配规范 ​

🎯Git 提交规范 ​

1. 分支管理 ​

2. 提交信息规范 ​

2.1 Type ​

2.2 Scope ​

2.3 Subject ​

2.4 Body ​

2.5 Footer ​

3. 提交示例 ​

4. Pull Request 规范 ​

🔧工具链规范 ​

1. 前端工具链 ​

2. 后端工具链 ​

💡开发流程规范 ​

1. 需求分析 ​

2. 设计阶段 ​

3. 开发阶段 ​

4. 测试阶段 ​

5. 部署阶段 ​

6. 维护阶段 ​

📚参考资料 ​

🤝贡献指南 ​

📄许可协议 ​

开发规范

📚规范概述

🎨前端开发规范

1. 代码风格

1.1 TypeScript 规范

1.2 Vue 规范

1.3 CSS 规范

2. 组件开发最佳实践

3. 状态管理最佳实践

4. API 调用最佳实践

5. 性能优化建议

6. 测试最佳实践

7. 代码审查要点

🐍后端开发规范

1. 代码风格

1.1 Python 规范

1.2 FastAPI 规范

2. 目录结构

3. 插件开发规范

4. 数据库规范

5. 认证和权限规范

6. 错误处理规范

7. 日志规范

📦FastApp 移动端开发规范

1. 代码风格

2. 目录结构

3. 页面开发规范

4. API 调用规范

5. 跨平台适配规范

🎯Git 提交规范

1. 分支管理

2. 提交信息规范

2.1 Type

2.2 Scope

2.3 Subject

2.4 Body

2.5 Footer

3. 提交示例

4. Pull Request 规范

🔧工具链规范

1. 前端工具链

2. 后端工具链

💡开发流程规范

1. 需求分析

2. 设计阶段

3. 开发阶段

4. 测试阶段

5. 部署阶段

6. 维护阶段

📚参考资料

🤝贡献指南

📄许可协议