Skip to content

Commit a2e5221

Browse files
committed
update docs
1 parent 30121cc commit a2e5221

File tree

7 files changed

+85
-46
lines changed

7 files changed

+85
-46
lines changed

docs/.vuepress/navbar.ts

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,9 +28,14 @@ export const myNavbar = defineNavbarConfig([
2828
icon: 'fluent-emoji-high-contrast:unicorn',
2929
link: 'https://github.com/fastapi-practices/fastapi_best_architecture/issues'
3030
},
31+
{
32+
text: '插件市场',
33+
icon: 'clarity:plugin-solid',
34+
link: '/plugins'
35+
},
3136
{
3237
text: '授权',
33-
icon: 'ri:key-2-fill',
38+
icon: 'fluent:person-key-20-filled',
3439
link: '/guide/summary/why.md#承诺'
3540
},
3641
{

docs/guide/reference/RBAC.md

Lines changed: 42 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22
title: RBAC
33
---
44

5-
我们通过两个自定义依赖组件,实现了 RBAC 的轻松集成,在 Java 或其他语言中,常见的方式可能是注解,但在 fastapi 中,依赖是它的亮点,也是核心
5+
我们通过两个自定义依赖组件,实现了 RBAC 的轻松集成,在 Java 或其他语言中,常见的方式可能是注解,但在 FastAPI 中,依赖是它的亮点,也是核心
66

77
## RBAC
88

9-
RBAC 提供了两种解决方案,第一种【角色菜单】可能更加常见,它可以设置按钮级别的控制规则,另外一种是【Casbin】,它非常灵活,可以通过模型定义多种
10-
控制规则(我认为它很好,性能也很出色)
9+
RBAC 提供了两种解决方案,分别为【角色菜单】、【Casbin】
10+
11+
【角色菜单】是各类语言 web 开发中比较常见的解决方案,它可以设置按钮级别的控制规则
12+
13+
【Casbin】是 Go 语言中比较流行的解决方案,它非常灵活,可以通过模型定义多种控制规则
1114

1215
### 角色菜单
1316

@@ -26,35 +29,37 @@ RBAC 提供了两种解决方案,第一种【角色菜单】可能更加常见
2629

2730
2. 添加接口依赖
2831

29-
只有在接口中填加此依赖时,才能自动应用此鉴权方式
32+
只有在接口中填加以下相关依赖时,才能自动应用此鉴权方式
3033

3134
```py{5-6}
3235
@router.post(
3336
'',
3437
summary='xxx',
3538
dependencies=[
36-
Depends(RequestPermission('sys:api:add')),
39+
Depends(RequestPermission('sys:api:add')), # 通常为 xxx:xxx:xxx
3740
DependsRBAC,
3841
],
3942
)
4043
```
4144

4245
3. 在菜单中添加权限标识
4346

44-
我们在接口依赖中可以看到 `sys:api:add` 之类的值,这些值正是对应着菜单中的权限标识,只有它们完全一致,并且用户拥有菜单时,才会获得相应的操作权限
45-
:::
47+
我们在接口依赖中可以看到 `sys:api:add` 之类的值,这些值正是对应着菜单中的权限标识,
48+
只有它们完全一致,并且用户拥有对应的菜单时,才会获得相应的操作权限
49+
50+
:::
4651

4752
### Casbin
4853

49-
Casbin 在 Go web 中应用更加广泛, 我们在最初架构设计时,参考了 go-admin,gin-vue-admin... 等优秀的开源项目,同时引入了
50-
Casbin,它在众多 python web 开源项目中可能是极为罕见的,并且,它的学习成本相对较高,如果你对此感兴趣,可以通过
51-
[Casbin 官网](https://casbin.org/docs/get-started) 进行学习,另外,可参考视频教程
54+
我们在最初架构设计时,参考了 go-admin,gin-vue-admin... 等优秀的开源项目,同时引入了
55+
Casbin,它在众多 python web 开源项目中可能是极为罕见的,并且,它的学习成本非常高,如果你对此感兴趣,可以通过
56+
[Casbin 官网](https://casbin.org/docs/get-started) 进行学习,另外,可参考视频教程
5257
[半小时彻底弄懂Casbin基础模型](https://www.bilibili.com/video/BV1qz4y167XP/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)、
5358
[Casbin的代码使用、api调用、自定义比较方法](https://www.bilibili.com/video/BV13r4y1M7AC/?spm_id_from=333.999.0.0&vd_source=958c4d7f9243c68a0ec9dcd327bad930)
54-
59+
,讲的是非常好
5560

56-
通过以上学习之后,我们再来看规则(不学习规则可能是天书),
57-
你可以通过此[编辑器](https://github.com/casbin/casbin-editor)进行规则验证
61+
通过以上学习之后,我们再来看内置规则(不学习 == 天书),
62+
你可以通过[编辑器](https://casbin.org/zh/docs/online-editor)进行模型规则验证
5863

5964
模型:
6065

@@ -88,5 +93,27 @@ g 策略 (**依赖 p 策略**):
8893
- 如果在 p 策略中添加了基于角色的访问权限, 则还需要在 g 策略中添加基于用户组的访问权限, 才能真正拥有访问权限<br>
8994
**格式**: 用户 uuid + 角色 role
9095
91-
- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限<br>
92-
但是拥有的不是用户角色的所有权限, 而只是单一的对应的 p 策略所添加的访问权限
96+
- 如果在 p 策略中添加了基于用户的访问权限, 则不添加相应的 g 策略能直接拥有访问权限,但是拥有的不是用户角色的所有权限,
97+
而只是单一的对应的 p 策略所添加的访问权限
98+
99+
## 解耦
100+
101+
在实际项目开发中,不可能同时存在两种 RBAC 解决方案,我们可以通过以下方式删除其中一种集成
102+
103+
### 角色菜单
104+
105+
- 删除 `backend/common/security/permission.py` 文件中的 `RequestPermission` 类及所有类调用
106+
- 删除 `backend/core/conf.py` 文件中的 `PERMISSION_MODE` 和 `RBAC_ROLE_MENU_EXCLUDE`
107+
- 删除 `backend/common/security/rbac.py` 文件中 `rbac_verify` 方法里面的 `if settings.PERMISSION_MODE == 'role-menu':`
108+
条件及相关代码
109+
110+
### Casbin
111+
112+
- 删除 `backend/app/admin/api/v1/sys/casbin.py`、`backend/app/admin/crud/crud_casbin.py`、
113+
`backend/app/admin/model/casbin_rule.py`、`backend/app/admin/schema/casbin_rule.py`、
114+
`backend/app/admin/service/casbin_service.py` 文件
115+
- 删除 `backend/core/conf.py` 文件中的 `RBAC_CASBIN_EXCLUDE`
116+
- 删除 `backend/common/security/rbac.py` 文件中 `enforcer` 方法
117+
- 删除 `backend/common/security/rbac.py` 文件中 `rbac_verify` 方法里面的 `if settings.PERMISSION_MODE == 'role-menu':`
118+
条件和 else 条件中的相关代码
119+
- 删除 casbin 相关依赖包

docs/guide/reference/db.md

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,12 @@
22
title: 切换数据库
33
---
44

5-
FBA 支持 MySQL、PostgreSQL 两种数据库,默认配置使用 MySQL
6-
75
::: tip
86
此教程仅适用于 pg 用户
97
:::
108

9+
FBA 支持 MySQL、PostgreSQL 两种数据库,默认配置使用 MySQL
10+
1111
如果本地未安装 pg,你可以使用以下命令创建 Docker 镜像
1212

1313
```shell
@@ -28,19 +28,19 @@ DATABASE_USER='postgres'
2828
DATABASE_PASSWORD='123456'
2929
```
3030

31-
## 注意事项
31+
## 解耦
3232

33-
FBA 在模型中使用 `with_variant` 尽可能兼容 MySQL 和 PostgreSQL,例如:
33+
在实际项目开发中,几乎不会存在同时兼容多种数据库的情况,我们在模型中使用 `with_variant` 尽可能的兼容 MySQL 和
34+
PostgreSQL,例如:
3435

35-
```python
36+
```python:no-line-numbers
3637
# [!code word:with_variant]
3738
remark: Mapped[str | None] = mapped_column(LONGTEXT().with_variant(TEXT, 'postgresql'))
3839
```
3940

40-
兼容性代码涉及的其他地方:
41-
42-
- 代码生成
43-
- 创建数据库链接
44-
- docker-compose.yml
45-
46-
如果你只使用其中一种数据库,可直接修改为数据库对应类型
41+
- 删除 `with_variant` 相关代码并且仅保留数据库对应的类型
42+
- 删除 `backend/core/conf.py` 文件中的 `DATABASE_TYPE` 及其相关的调用代码
43+
- 删除 `.env_example``.env` 文件中的 `DATABASE_TYPE`
44+
- 更新 `backend/templates/py/model.jinja` 文件中的 `database_type` 相关代码
45+
- 删除 `backend/sql` 目录中的 `mysql``postgresql` 文件夹
46+
- 删除 `docker-compose.yml` 文件中的 `fba_mysql``fba_postgres` 容器脚本

docs/guide/summary/fsm.md

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,10 +2,12 @@
22
title: 精简版本
33
---
44

5-
我们有一些简化版本的 fastapi 三层架构脚手架,但是它们的更新可能并不同步,这意味着,你可能无法及时在便捷版中获得新功能支持和问题修复
5+
::: warning
6+
FastAPI 三层架构脚手架精简版的更新可能并不同步,你可能无法及时的在这些版本中获得新功能支持和问题修复
7+
:::
68

79
> [!IMPORTANT]
8-
> 我们积极寻找这些版本仓库的维护人员,如果你对此感兴趣,请直接在对应仓库创建 ISSUES 或通过 Discord 与我们联系
10+
> 我们在积极寻找这些版本的维护人员,如果你对此感兴趣,请直接在对应仓库创建 ISSUES 或通过 Discord 与我们联系
911
1012
## SQLAlchemy
1113

docs/guide/summary/quick-start.md

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,15 @@
22
title: 快速开始
33
---
44

5+
::: caution
6+
==FBA 仅适用于资深 Python 后端开发人员==,如果您是非资深用户,请使用 [精简版](../summary/fsm.md)
7+
:::
8+
59
> [!IMPORTANT]
6-
> 请一字不落的认真对待此文档,并严格按照本文档的顺序启动项目,否则你有很大几率在启动过程中遇到各种问题
10+
> 我们建议新手用户从一些基础和简单的内容入手,这不仅是对自身学习的一种负责态度,也是为将来能够顺利掌握这一架构所奠定的坚实基础,欢迎加入我们的
11+
> Discord 社区进行讨论
12+
>
13+
> 最后,请认真对待此文档,并严格按照本文档的顺序启动项目,否则你有很大几率在启动过程中遇到各种问题
714
815
## 本地开发
916

@@ -68,17 +75,16 @@ title: 快速开始
6875
```
6976

7077
7. 按需修改配置文件 `core/conf.py``.env`
71-
72-
::: info
73-
默认情况下,首次启动不需要修改
74-
:::
75-
7678
8. 创建数据库表(三选一)
7779

7880
- 直接启动后端项目(自动创建)
7981
- 数据库迁移 [alembic](https://alembic.sqlalchemy.org/en/latest/tutorial.html)
8082

81-
::: details
83+
:::: details
84+
::: warning
85+
此方法暂不适用于 PostgreSQL 用户,详情请查看:[#1584](https://github.com/sqlalchemy/alembic/discussions/1584)
86+
:::
87+
8288
生成迁移文件
8389

8490
```shell
@@ -90,10 +96,10 @@ title: 快速开始
9096
```shell
9197
alembic upgrade head
9298
```
93-
:::
99+
::::
94100
- 执行 `backend/sql/` 目录下对应数据库的 `create_tables.sql` 脚本
95101

96-
9. ==(可选)== 启动 celery worker, beat 和 flower
102+
9. 启动 celery worker, beat 和 flower ==(可选)==
97103

98104
Celery 应用程序
99105

docs/guide/summary/why.md

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -6,16 +6,10 @@ title: 为什么选择我们?
66
import NpmBadge from 'vuepress-theme-plume/features/NpmBadge.vue'
77
</script>
88

9-
::: caution
10-
==FBA 仅适用于资深 Python 后端开发人员==,如果您是非资深用户,请查看 [精简版](#精简版)
11-
12-
我们建议新手用户从一些基础和简单的内容入手,这不仅是对自身学习的负责态度,也为将来能够顺利掌握这一架构奠定坚实的基础
13-
:::
14-
159
::: note
1610
我们不会去和其他架构做比较,我们认为每个架构都有自己的特点,适合不同的场景
1711

18-
我们的目标是提供一个最佳架构,让开发者可以快速上手,专注于业务逻辑的开发,所以我们只会不断完善和优化我们的架构,为开发者带来更好的体验
12+
我们的目标是提供一个最佳架构,让开发者可以快速上手,能够专注于业务逻辑的开发,所以我们只会不断完善和优化我们的架构,为开发者带来更好的体验
1913
:::
2014

2115
## 承诺

docs/plugins.md

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: 插件市场
3+
---
4+
5+
我们正在积极调研此功能,它将提供类似于 gin-vue-admin 中插件功能

0 commit comments

Comments
 (0)