Skip to content

Commit 4c36c7a

Browse files
wu-clanwu-clan
committed
update docs
1 parent c59a983 commit 4c36c7a

File tree

3 files changed

+132
-110
lines changed

3 files changed

+132
-110
lines changed

‎docs/code/fastapi-specific-standards-for-fba.mdc

Lines changed: 54 additions & 43 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,54 @@
1-
# FastAPI Best Architecture
2-
3-
您是 FastAPI 和可扩展 API 开发方面的专家，请严格遵循以下原则：
4-
5-
1. 依赖管理
6-
- 使用 FastAPI 的依赖注入系统管理状态和共享资源
7-
- 遵循项目的依赖版本要求：
8-
- Python 3.10+
9-
- FastAPI
10-
- Pydantic v2
11-
- Pydantic Settings @backend\core\conf.py
12-
- SQLAlchemy 2.0（如果使用 ORM 功能）
13-
- SQLAlchemy 配置: @backend\database\db.py
14-
2. SQLAlchemy 规范
15-
- 模型类文档只需描述它是什么表
16-
- 模型存在关系时需要在文件开头添加 `from __future__ import annotations`
17-
- 关系属性 Mapped[] 中的类不要使用字符串
18-
3. Schema 规范
19-
- schema 类文档只需描述简短几个字
20-
- 为 schema 属性添加 Field
21-
4. 路由处理规范
22-
- 同步操作使用 `def`
23-
- 异步操作使用 `async def`
24-
- `api` 目录下的文件自动跳过任何处理
25-
- 使用异步函数处理 I/O 绑定任务
26-
- 理解并遵循 @backend\common\response\response_schema.py 的返回模式
27-
- 保持 API 响应格式的一致性
28-
5. 性能优化规范
29-
- 接口函数内的阻塞型事件使用 run_in_threadpool 处理
30-
- 尽量减少阻塞 I/O 操作
31-
- 在所有数据库调用和外部 API 请求中使用异步操作
32-
- 使用 Redis 工具 @backend\database\redis.py，对静态数据和频繁访问的数据实施缓存
33-
- 优先考虑 API 性能指标（响应时间、延迟、吞吐量）
34-
6. 错误处理规范
35-
- 使用 FastAPI 的异常处理机制
36-
- 统一错误响应格式
37-
- 根据错误工厂 @backend\common\exception\errors.py 提供清晰的错误信息和错误码
38-
- 记录关键错误信息到日志系统 @backend\common\log.py
39-
7. 数据验证规范
40-
- 使用 Pydantic 模型进行数据验证
41-
- 定义清晰的请求和响应模型，参考：@backend\app\admin\schema\user.py
42-
- 合理使用字段验证器
43-
- 提供有意义的验证错误信息
1+
您是 FastAPI 和可扩展 API 开发方面的专家，请严格遵守以下编码规则：
2+
3+
## 依赖管理
4+
5+
- 使用 FastAPI 的依赖注入系统管理状态和共享资源
6+
- 遵循项目的依赖版本要求：
7+
- Python 3.10+
8+
- FastAPI
9+
- Pydantic v2
10+
- Pydantic Settings @backend\core\conf.py
11+
- SQLAlchemy 2.0（如果使用 ORM 功能）
12+
- SQLAlchemy 配置: @backend\database\db.py
13+
14+
## SQLAlchemy 规范
15+
16+
- 模型类文档只需描述它是什么表
17+
- 模型存在关系时需要在文件开头添加 `from __future__ import annotations`
18+
- 关系属性 Mapped[] 中的类不要使用字符串
19+
20+
## Schema 规范
21+
22+
- schema 类文档只需描述简短几个字
23+
- 为 schema 属性添加 Field
24+
25+
## 路由处理规范
26+
27+
- 同步操作使用 `def`
28+
- 异步操作使用 `async def`
29+
- `api` 目录下的文件自动跳过任何处理
30+
- 使用异步函数处理 I/O 绑定任务
31+
- 理解并遵循 @backend\common\response\response_schema.py 的返回模式
32+
- 保持 API 响应格式的一致性
33+
34+
## 性能优化规范
35+
36+
- 接口函数内的阻塞型事件使用 run_in_threadpool 处理
37+
- 尽量减少阻塞 I/O 操作
38+
- 在所有数据库调用和外部 API 请求中使用异步操作
39+
- 使用 Redis 工具 @backend\database\redis.py，对静态数据和频繁访问的数据实施缓存
40+
- 优先考虑 API 性能指标（响应时间、延迟、吞吐量）
41+
42+
## 错误处理规范
43+
44+
- 使用 FastAPI 的异常处理机制
45+
- 统一错误响应格式
46+
- 根据错误工厂 @backend\common\exception\errors.py 提供清晰的错误信息和错误码
47+
- 记录关键错误信息到日志系统 @backend\common\log.py
48+
49+
## 数据验证规范
50+
51+
- 使用 Pydantic 模型进行数据验证
52+
- 定义清晰的请求和响应模型，参考：@backend\app\admin\schema\user.py
53+
- 不要新增字段验证器
54+
- 提供有意义的验证错误信息

‎docs/code/python-code-standards.mdc

Lines changed: 77 additions & 66 deletions
Original file line numberDiff line numberDiff line change
@@ -1,68 +1,79 @@
1-
# Python 3.10+
1+
您是 Python 3.10+ 方面的专家，请严格遵守以下编码规则：
22

3-
您是 Python 3.10+ 方面的专家，请严格遵循以下规则：
3+
## 类型注解规范
44

5-
1. 类型注解规范
6-
- 使用 Python 3.10+ 的类型/注解语法
7-
- 只在必要时使用 `Any` 类型，如果使用了则必须保留
8-
- 为所有函数参数和返回值添加类型注解，args, kwargs 参数直接忽略注解
9-
- 为字典返回值添加具体的类型注解（如 `dict[str, Any]`）
10-
- 为列表返回值添加具体的类型注解（如 `list[dict[str, str]]`）
11-
2. 文档注释规范
12-
- 不要在文件开头添加注释
13-
- 函数文档格式如下：
14-
1. 有参数的函数：
15-
- 使用多行文档字符串
16-
- 第一行写函数描述
17-
- 空一行
18-
- 参数说明格式为 ":param 参数名: 参数说明"
19-
- return 格式为 ":return:"，无需添加任何返回说明
20-
2. 无参数的函数：
21-
- 使用单行文档字符串
22-
- 只写函数描述
23-
- 描述和引号在同一行
24-
3. 通用要求：
25-
- 函数描述要简洁明了
26-
- 不需要举例说明
27-
- 中英文之间要有空格
28-
- 参数说明要具体和清晰
29-
- 如果函数没有入参且描述只有简短文字，那么引号和内容写在同一行
30-
- 如果函数被 model_validator 或 field_validator 注释，则只需添加函数描述即可
31-
3. 代码逻辑规范
32-
- 在保证逻辑清晰的情况下，尽量避免使用多元表达式（如三元运算符）
33-
- 保持代码的可读性和可维护性
34-
- 使用提前返回模式简化代码
35-
- 移除不必要的中间变量
36-
- 添加适当的空行，提高代码可读性
37-
- 优先处理错误和边缘案例
38-
- 只要必要时添加 try
39-
- 对错误条件使用提前返回，以避免嵌套较深的 if 语句
40-
- 避免不必要的 else 语句，而应使用 if-return 模式
41-
- 实施适当的错误记录和用户友好型错误信息
42-
- 使用自定义错误类型或错误工厂进行一致的错误处理
43-
4. 代码格式规范
44-
- 统一代码风格
45-
- 保持适当的空行
46-
- 优化长行（超过 120 个字符）的格式
47-
- 使用括号进行换行
48-
- 保持一致的缩进
49-
5. 代码注释规范
50-
- 每个 py 文件开头都需添加以下内容
51-
```
52-
#!/usr/bin/env python3
53-
# -*- coding: utf-8 -*-
54-
```
55-
- 合理的注释，避免不必要的注释
56-
- 中英文之间应包加空格
57-
- 注释文字描述应具体和清晰
58-
- 注释要让人视觉上更清晰
59-
6. 命名规范
60-
- 变量名要具有描述性
61-
- 避免使用单字母变量名（除非是循环变量）
62-
- 使用下划线命名法（snake_case）
63-
- 类名使用大驼峰命名法（PascalCase）
64-
7. 函数定义规范
65-
- 纯函数使用 `def`
66-
- 异步操作使用 `async def`
67-
- 函数尽量单一职责，避免过于复杂的函数，但也不要过于琐碎
68-
- 不要擅自修改任何参数命名
5+
- 使用 Python 3.10+ 的类型/注解语法
6+
- 只在必要时使用 `Any` 类型，如果使用了则必须保留
7+
- 为所有函数参数和返回值添加类型注解，args, kwargs 参数直接忽略注解
8+
- 为字典返回值添加具体的类型注解（如 `dict[str, Any]`）
9+
- 为列表返回值添加具体的类型注解（如 `list[dict[str, str]]`）
10+
11+
## 文档注释规范
12+
13+
- 不要在文件开头添加注释
14+
- 函数文档格式如下：
15+
1. 有参数的函数：
16+
- 使用多行文档字符串
17+
- 第一行写函数描述
18+
- 空一行
19+
- 参数说明格式为 ":param 参数名: 参数说明"
20+
- 返回说明格式为 ":return:"
21+
2. 无参数的函数：
22+
- 使用单行文档字符串
23+
- 只写函数描述
24+
- 描述和引号在同一行
25+
3. 通用要求：
26+
- 函数描述要简洁明了
27+
- 不需要举例说明
28+
- 中英文之间要有空格
29+
- 参数说明要具体和清晰
30+
- 如果函数没有入参且描述只有简短文字，那么引号和内容写在同一行
31+
- 如果函数被 model_validator 或 field_validator 注释，则只需添加函数描述即可
32+
33+
## 代码逻辑规范
34+
35+
- 在保证逻辑清晰的情况下，尽量避免使用多元表达式（如三元运算符）
36+
- 保持代码的可读性和可维护性
37+
- 使用提前返回模式简化代码
38+
- 移除不必要的中间变量
39+
- 添加适当的空行，提高代码可读性
40+
- 优先处理错误和边缘案例
41+
- 只要必要时添加 try
42+
- 对错误条件使用提前返回，以避免嵌套较深的 if 语句
43+
- 避免不必要的 else 语句，而应使用 if-return 模式
44+
- 实施适当的错误记录和用户友好型错误信息
45+
- 使用自定义错误类型或错误工厂进行一致的错误处理
46+
47+
## 代码格式规范
48+
49+
- 统一代码风格
50+
- 保持适当的空行
51+
- 优化长行（超过 120 个字符）的格式
52+
- 使用括号进行换行
53+
- 保持一致的缩进
54+
55+
## 代码注释规范
56+
57+
- 每个 py 文件开头都需添加以下内容
58+
```
59+
#!/usr/bin/env python3
60+
# -*- coding: utf-8 -*-
61+
```
62+
- 合理的注释，避免不必要的注释
63+
- 中英文之间应包加空格
64+
- 注释文字描述应具体和清晰
65+
- 注释要让人视觉上更清晰
66+
67+
## 命名规范
68+
69+
- 变量名要具有描述性
70+
- 避免使用单字母变量名（除非是循环变量）
71+
- 使用下划线命名法（snake_case）
72+
- 类名使用大驼峰命名法（PascalCase）
73+
74+
## 函数定义规范
75+
76+
- 纯函数使用 `def`
77+
- 异步操作使用 `async def`
78+
- 函数尽量单一职责，避免过于复杂的函数，但也不要过于琐碎
79+
- 不要擅自修改任何参数命名

‎docs/guide/ide/cursor.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ Discord 社区与我们分享吧 🤗
2828
### FastAPI 特定规范
2929

3030
::: tip
31-
此规则特定于 fba，不建议您将它用于其他 FastAPI 项目
31+
此规则特定于 fba 项目
3232
:::
3333

3434
`fastapi-specific-standards-for-fba.mdc`

0 commit comments

Comments
 (0)