Skip to content

Commit cce9990

Browse files
wu-clanwu-clan
committed
update docs
1 parent fad2174 commit cce9990

File tree

9 files changed

+138
-19
lines changed

9 files changed

+138
-19
lines changed

‎docs/.vuepress/sidebar.ts

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ export const mySidebar: SidebarMulti = {
1919
collapsed: false,
2020
prefix: 'reference/',
2121
items: [
22+
{text: '路由', link: 'route'},
2223
{text: 'JWT', link: 'jwt'},
2324
{text: '跨域', link: 'CORS'},
2425
{text: 'RBAC', link: 'RBAC'},
@@ -41,6 +42,7 @@ export const mySidebar: SidebarMulti = {
4142
collapsed: false,
4243
prefix: 'mixin/',
4344
items: [
45+
{text: 'CRUD', link: 'CRUD'},
4446
{text: '用户信息', link: 'user', icon: 'mdi:planet'},
4547
]
4648
},

‎docs/guide/mixin/CRUD.md

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
---
2+
title: CRUD
3+
---
4+
5+
CRUD Mixin 位于 `common/model.py` 文件中
6+
7+
## 主键
8+
9+
我们未提供自动主键模式，而是必须通过手动定义的方式进行主键声明
10+
11+
```python
12+
# 通用 Mapped 类型主键, 需手动添加，参考以下使用方式
13+
# MappedBase -> id: Mapped[id_key]
14+
# DataClassBase && Base -> id: Mapped[id_key] = mapped_column(init=False)
15+
id_key = Annotated[
16+
int, mapped_column(primary_key=True, index=True, autoincrement=True, sort_order=-999, comment='主键id')
17+
]
18+
```
19+
20+
## 日期时间
21+
22+
日期时间 Mixin 将自动集成到 Base 类中，如果模型父类为 Base，将自动应用
23+
24+
```python
25+
class DateTimeMixin(MappedAsDataclass):
26+
"""日期时间 Mixin 数据类"""
27+
28+
created_time: Mapped[datetime] = mapped_column(
29+
DateTime(timezone=True), init=False, default_factory=timezone.now, sort_order=999, comment='创建时间'
30+
)
31+
updated_time: Mapped[datetime | None] = mapped_column(
32+
DateTime(timezone=True), init=False, onupdate=timezone.now, sort_order=999, comment='更新时间'
33+
)
34+
```
35+
36+
## 数据类基类
37+
38+
[MappedAsDataclass](https://docs.sqlalchemy.org/en/20/orm/dataclasses.html#orm-declarative-native-dataclasses)
39+
40+
声明性数据类基类, 它将带有数据类集成, 允许使用更高级配置；此基类适用于==不包含日期时间的模型==
41+
42+
```python
43+
class DataClassBase(MappedAsDataclass, MappedBase):
44+
__abstract__ = True
45+
```
46+
47+
## Base 基类
48+
49+
包含基础表结构的数据类基类；此基类适用于大多数模型
50+
51+
```python
52+
class Base(DataClassBase, DateTimeMixin):
53+
__abstract__ = True
54+
```

‎docs/guide/mixin/user.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,18 @@ title: 用户信息
33
---
44

55
<div align="center">
6-
76
此内容为非公开内容，扫码加入知识星球，即可获取独家内容
87

9-
<p style="color: rgb(160, 160, 160);">
10-
请注意，我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
11-
<br/>
12-
附：加入 Discord 频道，可领取免费体验资格
8+
<a href="https://t.zsxq.com/virtV">内容跳转</a>
9+
10+
<span style="color: rgb(110, 110, 110);">
11+
我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
12+
</span>
13+
14+
<p style="font-size: 14px; color: rgb(110,110,110);">
15+
附：星球用作
16+
<a href="http://localhost:8080/fastapi_best_architecture_docs/sponsors.html#%E6%9C%89%E5%81%BF%E8%B5%9E%E5%8A%A9">有偿赞助</a>
17+
，加入 Discord 社区，可领取免费体验资格
1318
</p>
1419

1520
<img height="349" width="415" src="https://wu-clan.github.io/picx-images-hosting/知识星球.png" alt="知识星球">

‎docs/guide/reference/CRUD.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
title: CRUD
33
---
44

5-
我们在 FBA 中使用 [sqlalchemy-crud-plus](https://wu-clan.github.io/sqlalchemy-crud-plus/) 作为数据库操作的基类，
5+
我们在 FBA 中使用 [sqlalchemy-crud-plus](https://wu-clan.github.io/sqlalchemy-crud-plus/) 作为数据库操作基类，
66
它是一款由我们自主构建的基于 SQLAlchemy 2.0 的高级异步 CRUD SDK，它适用于所有 FastAPI + SQLAlchemy 项目
77

88
<RepoCard repo="wu-clan/sqlalchemy-crud-plus" />

‎docs/guide/reference/celery.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,18 @@ title: Celery
33
---
44

55
<div align="center">
6-
76
此内容为非公开内容，扫码加入知识星球，即可获取独家内容
87

9-
<p style="color: rgb(160, 160, 160);">
10-
请注意，我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
11-
<br/>
12-
附：加入 Discord 频道，可领取免费体验资格
8+
<a href="https://t.zsxq.com/qk5gZ">内容跳转</a>
9+
10+
<span style="color: rgb(110, 110, 110);">
11+
我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
12+
</span>
13+
14+
<p style="font-size: 14px; color: rgb(110,110,110);">
15+
附：星球用作
16+
<a href="http://localhost:8080/fastapi_best_architecture_docs/sponsors.html#%E6%9C%89%E5%81%BF%E8%B5%9E%E5%8A%A9">有偿赞助</a>
17+
，加入 Discord 社区，可领取免费体验资格
1318
</p>
1419

1520
<img height="349" width="415" src="https://wu-clan.github.io/picx-images-hosting/知识星球.png" alt="知识星球">

‎docs/guide/reference/data-rule.md

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,18 @@ title: 数据规则
33
---
44

55
<div align="center">
6-
76
此内容为非公开内容，扫码加入知识星球，即可获取独家内容
87

9-
<p style="color: rgb(160, 160, 160);">
10-
请注意，我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
11-
<br/>
12-
附：加入 Discord 频道，可领取免费体验资格
8+
<a href="https://t.zsxq.com/qlZyT">内容跳转</a>
9+
10+
<span style="color: rgb(110, 110, 110);">
11+
我们不保证星球内容的更新频率，您可以依据星球规则进行全额退款
12+
</span>
13+
14+
<p style="font-size: 14px; color: rgb(110,110,110);">
15+
附：星球用作
16+
<a href="http://localhost:8080/fastapi_best_architecture_docs/sponsors.html#%E6%9C%89%E5%81%BF%E8%B5%9E%E5%8A%A9">有偿赞助</a>
17+
，加入 Discord 社区，可领取免费体验资格
1318
</p>
1419

1520
<img height="349" width="415" src="https://wu-clan.github.io/picx-images-hosting/知识星球.png" alt="知识星球">

‎docs/guide/reference/route.md

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: 路由
3+
---
4+
5+
FBA 中的路由遵循 Restful API 规范
6+
7+
## 路由结构
8+
9+
我们有一个关于路由器的历史讨论，如果你感兴趣，可以查看：[#4](https://github.com/fastapi-practices/fastapi_best_architecture/discussions/4)
10+
11+
当前路由结构如下所示：
12+
13+
::: file-tree
14+
15+
- backend/ 后端
16+
- app/ 应用
17+
- xxx 某自定义应用
18+
- api 接口
19+
- v1（包含子包）
20+
- xxx 子包
21+
- _\_init\_\_.py 在此文件内导入 xxx.py 中的路由
22+
- xxx.py
23+
- ...
24+
- xxx/ 子包
25+
- ...
26+
- v2/
27+
- ...
28+
- router.py 在此文件内注册所有子包路由
29+
- xxx 某自定义应用
30+
- api 接口
31+
- v1（不包含子包）
32+
- _\_init\_\_.py 不做任何操作
33+
- xxx.py
34+
- ...
35+
- router.py 在此文件内注册所有 xxx.py 中的路由
36+
- ...
37+
- _\_init\_\_.py
38+
- router.py 在此文件内注册所有 app 路由
39+
40+
:::
41+
42+
::: warning
43+
我们统一命名了所有接口路由参数为 router，这很有助于我们编写接口，但是，不可忽略的是，在注册路由时，一定要注意我们的导入方式，在
44+
FBA 中，我们可以查看所有路由的导入，它们看起来像 `from backend.app.admin.api.v1.sys.api import router as api_router`
45+
，我们这里务必导入文件内的路由参数 `router`，为了避免参数名称冲突，我们可以使用 `as` 为路由参数起一个别名
46+
:::

‎docs/guide/summary/intro.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,10 @@ mvc 架构作为常规设计模式，在 python web 中很常见，但是三层
7070
- model/ 模型
7171
- schema/ 数据传输
7272
- service/ 服务
73-
- tests/ 测试
73+
- tests/ 单元测试
7474
- generator/ 代码生成
7575
- task/ 任务
76+
- ...
7677
- common/ 公共资源
7778
- core/ 核心配置
7879
- database/ 数据库连接
@@ -85,7 +86,8 @@ mvc 架构作为常规设计模式，在 python web 中很常见，但是三层
8586
- utils/ 工具包
8687
- deploy/ 服务器部署
8788
- ...
88-
:::
89+
90+
:::
8991

9092
## 贡献者
9193

‎docs/guide/summary/why.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -140,8 +140,8 @@ FBA
140140
141141
<CardGrid>
142142
<RepoCard repo="wu-clan/sqlalchemy-crud-plus" />
143-
<RepoCard repo="wu-clan/fast-captcha" />
144143
<RepoCard repo="wu-clan/fastapi_scheduler" />
144+
<RepoCard repo="wu-clan/fast-captcha" />
145145
<RepoCard repo="wu-clan/fastapi-oauth20" />
146146
</CardGrid>
147147

0 commit comments

Comments
 (0)