Skip to content

Commit 73930a0

Browse files
wu-clanwu-clan
committed
update docs
1 parent 61f8a5a commit 73930a0

File tree

5 files changed

+211
-34
lines changed

5 files changed

+211
-34
lines changed

‎.prettierrc.json5

+18
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
// 在 vscode 中模拟 IDEA markdown 格式化
2+
{
3+
"proseWrap": "preserve", // 超过宽度强制换行
4+
"tabWidth": 2, // 缩进使用 2 个空格
5+
"useTabs": false, // 使用空格而不是制表符
6+
"printWidth": 80, // 设置行宽为 120
7+
"singleQuote": false, // 使用双引号
8+
"trailingComma": "none", // 不添加尾随逗号
9+
"overrides": [
10+
{
11+
"files": "*.md", // 针对 Markdown 文件
12+
"options": {
13+
"parser": "markdown", // 显式指定 Markdown 解析器
14+
"embeddedLanguageFormatting": "off" // 关闭 Markdown 中嵌入代码的格式化
15+
}
16+
}
17+
]
18+
}

‎docs/.vuepress/sidebar.ts

+40-30
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
1-
import {SidebarMulti} from "vuepress-theme-plume/lib/shared";
1+
import { text } from "mermaid/dist/rendering-util/rendering-elements/shapes/text.js";
2+
import { SidebarMulti } from "vuepress-theme-plume/lib/shared";
23

34

45
export const mySidebar: SidebarMulti = {
@@ -8,53 +9,62 @@ export const mySidebar: SidebarMulti = {
89
collapsed: false,
910
prefix: 'summary/',
1011
items: [
11-
{text: '简介', link: 'intro'},
12-
{text: '快速开始', link: 'quick-start'},
13-
{text: 'Visual Studio Code', link: 'vscode'},
14-
{text: '为什么选择我们？', link: 'why'},
15-
{text: '精简版', link: 'fsm'},
12+
{ text: '简介', link: 'intro' },
13+
{ text: '快速开始', link: 'quick-start' },
14+
{ text: '为什么选择我们？', link: 'why' },
15+
{ text: '精简版', link: 'fsm' },
16+
]
17+
},
18+
{
19+
text: '编辑器',
20+
collapsed: false,
21+
prefix: 'ide/',
22+
items: [
23+
{ text: 'Visual Studio Code', link: 'vscode' },
24+
{ text: 'Cursor', link: 'cursor' },
1625
]
1726
},
1827
{
1928
text: '参考',
2029
collapsed: false,
2130
prefix: 'reference/',
2231
items: [
23-
{text: '路由', link: 'router'},
24-
{text: 'CRUD', link: 'CRUD'},
25-
{text: '接口响应', link: 'response'},
26-
{text: '分页', link: 'pagination'},
27-
{text: '自定义异常', link: '/planet', icon: 'fluent-color:receipt-16'},
28-
{text: '切换数据库', link: 'db'},
29-
{text: '鉴权', link: 'permission'},
30-
{text: 'JWT', link: 'jwt'},
31-
{text: 'RBAC', link: 'RBAC'},
32-
{text: '数据规则', link: '/planet', icon: 'fluent-color:video-16'},
33-
{text: '代码生成', link: 'code-generation'},
34-
{text: '跨域', link: 'CORS'},
35-
{text: '事务', link: 'transaction'},
36-
{text: 'Celery', link: '/planet', icon: 'fluent-color:video-16'},
37-
{text: 'APScheduler', link: 'apscheduler'},
32+
{ text: '路由', link: 'router' },
33+
{ text: 'CRUD', link: 'CRUD' },
34+
{ text: 'Schema', link: 'schema' },
35+
{ text: '接口响应', link: 'response' },
36+
{ text: '分页', link: 'pagination' },
37+
{ text: '自定义异常', link: '/planet', icon: 'fluent-color:receipt-16' },
38+
{ text: '切换数据库', link: 'db' },
39+
{ text: '鉴权', link: 'permission' },
40+
{ text: 'JWT', link: 'jwt' },
41+
{ text: 'RBAC', link: 'RBAC' },
42+
{ text: '数据规则', link: '/planet', icon: 'fluent-color:video-16' },
43+
{ text: '代码生成', link: 'code-generation' },
44+
{ text: '跨域', link: 'CORS' },
45+
{ text: '事务', link: 'transaction' },
46+
{ text: 'Celery', link: '/planet', icon: 'fluent-color:video-16' },
47+
{ text: 'APScheduler', link: 'apscheduler' },
3848
// {text: '日志分析', link: '/planet', icon: 'fluent-color:receipt-16'},
39-
{text: 'Socketio', link: '/planet', icon: 'fluent-color:receipt-16'},
49+
{ text: 'Socketio', link: '/planet', icon: 'fluent-color:receipt-16' },
4050
]
4151
},
4252
{
4353
text: 'Mixin',
4454
collapsed: false,
4555
prefix: 'mixin/',
4656
items: [
47-
{text: 'CRUD', link: 'CRUD'},
48-
{text: '操作人信息', link: '/planet', icon: 'fluent-color:receipt-16'},
57+
{ text: 'CRUD', link: 'CRUD' },
58+
{ text: '操作人信息', link: '/planet', icon: 'fluent-color:receipt-16' },
4959
]
5060
},
5161
{
5262
text: '部署',
5363
collapsed: false,
5464
prefix: 'deploy/',
5565
items: [
56-
{text: 'Docker', link: 'Docker'},
57-
{text: '传统', link: 'legacy', icon: 'fluent-color:video-16'},
66+
{ text: 'Docker', link: 'Docker' },
67+
{ text: '传统', link: 'legacy', icon: 'fluent-color:video-16' },
5868
]
5969
},
6070
],
@@ -63,10 +73,10 @@ export const mySidebar: SidebarMulti = {
6373
text: '插件',
6474
collapsed: false,
6575
items: [
66-
{text: '前言', link: 'before'},
67-
{text: '插件开发', link: 'dev'},
68-
{text: '插件发布', link: 'publish'},
69-
{text: '插件市场', link: 'market'},
76+
{ text: '前言', link: 'before' },
77+
{ text: '插件开发', link: 'dev' },
78+
{ text: '插件发布', link: 'publish' },
79+
{ text: '插件市场', link: 'market' },
7080
]
7181
}
7282
]

‎docs/guide/ide/cursor.md

+125
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
---
2+
title: cursor
3+
---
4+
5+
官网地址：[cursor](https://www.cursor.com/)
6+
7+
## 规则
8+
9+
我们在 cursor 中为 fba 量身打造了特定规则，它们可有效地帮助您生成高质量且符合规范的代码，如果您有更好的案例，请通过
10+
Discord 社区与我们分享吧 🤗
11+
12+
::: warning
13+
我们未对规则进行 token 消耗量测试，请根据实际情况自行选择
14+
:::
15+
16+
首先，在 fba 根目录创建 `.cursor\rules` 目录，然后添加以下规则：
17+
18+
### Python 编码规范
19+
20+
::: note
21+
此规则也可用于其他 Python 3.10+ 项目
22+
:::
23+
24+
文件名：`python-code-standards.mdc`
25+
26+
```mdc
27+
## 类型注解规范
28+
29+
- 使用 Python 3.10+ 的类型注解语法
30+
- 只在必要时使用 `Any` 类型，如果使用了则必须保留
31+
- 为所有函数参数和返回值添加类型注解
32+
- 为字典返回值添加具体的类型注解（如 `dict[str, Any]`）
33+
- 为列表返回值添加具体的类型注解（如 `list[dict[str, str]]`）
34+
35+
## 文档注释规范
36+
37+
- 只包含 `:param` 和 `:return`
38+
- `:return:` 后面不添加注释
39+
- 保持中英文之间的空格
40+
- 参数说明要具体和清晰
41+
- 函数描述要简洁明了
42+
43+
## 代码逻辑规范
44+
45+
- 在保证逻辑清晰的情况下，尽量避免使用多元表达式（如三元运算符）
46+
- 保持代码的可读性和可维护性
47+
- 使用提前返回模式简化代码
48+
- 移除不必要的中间变量
49+
- 添加适当的空行，提高代码可读性
50+
- 优先处理错误和边缘案例
51+
- 对错误条件使用提前返回，以避免嵌套较深的 if 语句
52+
- 避免不必要的 else 语句，而应使用 if-return 模式
53+
- 实施适当的错误记录和用户友好型错误信息
54+
- 使用自定义错误类型或错误工厂进行一致的错误处理
55+
56+
## 代码格式规范
57+
58+
- 统一代码风格
59+
- 保持适当的空行
60+
- 优化长行（超过 120 个字符）的格式
61+
- 使用括号进行换行
62+
- 保持一致的缩进
63+
64+
## 命名规范
65+
66+
- 变量名要具有描述性
67+
- 避免使用单字母变量名（除非是循环变量）
68+
- 使用下划线命名法（snake_case）
69+
- 类名使用大驼峰命名法（PascalCase）
70+
71+
## 函数定义规范
72+
73+
- 纯函数使用 `def`
74+
- 异步操作使用 `async def`
75+
- 函数尽量单一职责，避免过于复杂的函数，但也不要过于琐碎
76+
```
77+
78+
### FastAPI 特定规范
79+
80+
::: tip
81+
此规则特定于 fba，不建议您将它用于其他 FastAPI 项目
82+
:::
83+
84+
文件名：`fastapi-specific-standards-for-fba.mdc`
85+
86+
```mdc
87+
## 依赖管理
88+
89+
- 使用 FastAPI 的依赖注入系统管理状态和共享资源
90+
- 遵循项目的依赖版本要求：
91+
- FastAPI
92+
- Pydantic v2
93+
- SQLAlchemy 2.0（如果使用 ORM 功能）
94+
- SQLAlchemy 配置: @backend\database\db.py
95+
96+
## 路由处理规范
97+
98+
- 同步操作使用 `def`
99+
- 异步操作使用 `async def`
100+
- 使用异步函数处理 I/O 绑定任务
101+
- 理解并遵循 @backend\common\response\response_schema.py 的返回模式
102+
- 保持 API 响应格式的一致性
103+
104+
## 性能优化规范
105+
106+
- 接口函数内的阻塞型事件使用 run_in_threadpool 处理
107+
- 尽量减少阻塞 I/O 操作
108+
- 在所有数据库调用和外部 API 请求中使用异步操作
109+
- 使用 Redis 工具 @backend\database\redis.py，对静态数据和频繁访问的数据实施缓存
110+
- 优先考虑 API 性能指标（响应时间、延迟、吞吐量）
111+
112+
## 错误处理规范
113+
114+
- 使用 FastAPI 的异常处理机制
115+
- 统一错误响应格式
116+
- 根据错误工厂 @backend\common\exception\errors.py 提供清晰的错误信息和错误码
117+
- 记录关键错误信息到日志系统 @backend\common\log.py
118+
119+
## 数据验证规范
120+
121+
- 使用 Pydantic 模型进行数据验证
122+
- 定义清晰的请求和响应模型，参考：@backend\app\admin\schema\user.py
123+
- 合理使用字段验证器
124+
- 提供有意义的验证错误信息
125+
```

‎docs/guide/summary/vscode.md ‎docs/guide/ide/vscode.md

+2-4
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,7 @@
22
title: vscode
33
---
44

5-
::: tip
6-
此章节仅限于 vscode 后端开发用户
7-
:::
5+
官网地址：[visualstudio](https://code.visualstudio.com/)
86

97
## DEBUG
108

@@ -24,7 +22,7 @@ title: vscode
2422
//"python": "${workspaceFolder}/.venv/bin/python", // MacOS or Linux
2523
//"python": "${workspaceFolder}/.venv/Scripts/python.exe", // Windows
2624
"env": {
27-
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}",
25+
"PYTHONPATH": "${workspaceFolder};${env:PYTHONPATH}",
2826
},
2927
"envFile": "${workspaceFolder}/backend/.env",
3028
"args": [

‎docs/guide/reference/schema.md

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: schema
3+
---
4+
5+
在 fba 中，我们为 Schema 进行了大量量身定制，详情请查看源代码：`backend\common\schema.py`
6+
7+
## 类定义
8+
9+
针对 schema 类，fba 遵循以下规范：
10+
11+
- 基础 schema: `XxxSchemaBase(SchemaBase)`
12+
- 接口入参：`XxxParam(XxxSchemaBase)`
13+
- 新增入参：`CreateXxxParam(XxxSchemaBase)`
14+
- 更新入参：`UpdateXxxParam(XxxSchemaBase)`
15+
- 查询详情：`GetXxxDetail(XxxSchemaBase)`
16+
- 查询详情（包含关系）：`GetXxxWithRelationDetail(XxxSchemaBase)`
17+
18+
## Field
19+
20+
fba 内部暂未大量使用 Field，它后期可能被添加，但最也仅仅是将其用于添加描述，这很有助于接口文档字段说明，但也有可能因此
21+
PR 改变计划
22+
：[Allow to have multiple Query parameter models](https://github.com/fastapi/fastapi/pull/12944#pullrequestreview-2588580175)
23+
24+
## 驼峰返回
25+
26+
详见：[接口响应](response.md#驼峰返回)

0 commit comments

Comments
 (0)