Skip to content

Commit 06ffa4d

Browse files
committed
update docs
1 parent c261946 commit 06ffa4d

File tree

8 files changed

+125
-8
lines changed

8 files changed

+125
-8
lines changed

docs/.vuepress/config.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ export default defineUserConfig({
3232
permalink: false,
3333
createTime: false,
3434
},
35-
bulletin: myBulletin,
35+
// bulletin: myBulletin,
3636
sidebar: mySidebar,
3737
navbar: myNavbar,
3838
logo: 'https://wu-clan.github.io/picx-images-hosting/logo/fba.png',
Loading
Loading

docs/.vuepress/sidebar.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ export const mySidebar: SidebarMulti = {
2323
{text: 'JWT', link: 'jwt'},
2424
{text: 'CRUD', link: 'CRUD'},
2525
{text: '接口响应', link: 'response'},
26-
{text: '分页', link: 'paginate'},
26+
{text: '分页', link: 'pagination'},
2727
{text: '自定义异常', link: '/planet', icon: 'fluent-color:receipt-16'},
2828
{text: '切换数据库', link: 'db'},
2929
{text: '代码生成', link: 'code-generation'},
File renamed without changes.

docs/guide/reference/response.md

Lines changed: 120 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,4 +2,123 @@
22
title: 接口响应
33
---
44

5-
coming soon...
5+
我们为 FBA 开发了十分灵活且健全的接口响应系统,它同时适用于任何 FastAPI 应用
6+
7+
## 响应状态码
8+
9+
在文件 `backend/common/response/response_code.py` 中内置了多种定义响应状态码的方式,我们可以根据 `CustomResponseCode`
10+
`CustomResponse` 定义自己需要的的响应状态码,因为在实际项目中,响应状态码并没有统一的标准
11+
12+
当我们定义好自定义响应状态码之后,可以向下方这样使用
13+
14+
```python{3-4}
15+
@router.get('/test')
16+
def test() -> ResponseModel:
17+
res = CustomResponse(code=0, msg='成功')
18+
return ResponseModel(res=res, data={'test': 'test'})
19+
```
20+
21+
## 统一返回模型
22+
23+
在常规 web 应用开发中,通常情况下,响应结构总是统一的,但在 FastAPI 的官方教程中,并没有提示我们该如何这样做,其实,这很简单,
24+
只需我们提供一个统一的 pydantic 模型
25+
26+
```python
27+
class ResponseModel(BaseModel):
28+
# TODO: json_encoders 配置失效: https://github.com/tiangolo/fastapi/discussions/10252
29+
model_config = ConfigDict(json_encoders={datetime: lambda x: x.strftime(settings.DATETIME_FORMAT)})
30+
31+
code: int = CustomResponseCode.HTTP_200.code
32+
msg: str = CustomResponseCode.HTTP_200.msg
33+
data: Any | None = None
34+
```
35+
36+
以上是我们在 FBA 中的内部实现,由于我们使用的是 pydantic-v2,所以,`json_encoders` 可能暂时无法按预期工作;
37+
38+
以下是使用此模型进行返回的示例(遵循 FastAPI 官方教程),`response_model` 参数和 `->` 类型我们只需选择其中一种方式即可,因为
39+
FastAPI 会在内部自动解析并获取最终响应结构
40+
41+
`response_model` 参数
42+
43+
```python{1}
44+
@router.get('/test', response_model=ResponseModel)
45+
def test():
46+
return ResponseModel(data={'test': 'test'})
47+
```
48+
49+
`->` 类型
50+
51+
```python{2}
52+
@router.get('/test')
53+
def test() -> ResponseModel:
54+
return ResponseModel(data={'test': 'test'})
55+
```
56+
57+
## Schema 模式
58+
59+
上面我们已经讲解了统一返回模型,但是,FastAPI 中的优势之一好包括,完全自动的 openAPI 以及文档,如果我们全局使用
60+
ResponseModel 做为统一响应模型,你会在 Swagger 文档得到(如图所示)
61+
62+
![response_model](/images/response_model.png)
63+
64+
显然,我们无法获取响应 Schema 中的 data 结构,前端同事找到你,你会告诉他们,你请求一下不就行了?(没毛病,但显然不太友好),下面就是我们的解决办法
65+
66+
```python{1,3}
67+
@router.get('/test', response_model=ResponseSchemaModel[GetApiListDetails])
68+
def test():
69+
return ResponseSchemaModel[GetApiListDetails](data=GetApiListDetails(...))
70+
```
71+
72+
我们可以看到,这里其实和统一响应模型 ResponseModel 差不多,关键就在于我们这里多了一个 `[xxxSchema]`,没错,这就是关键,此时我们再来看一眼
73+
Swagger 文档
74+
75+
![response_schema_model](/images/response_schema_model.png)
76+
77+
我们可以看到,响应 Schema 中的 data 已经包含我们的响应体结构了,响应体结构正式解析的 `[]` 的 Schema 模型,它们是对应的,如果返回的数据结构与
78+
Schema 不一致,将引发解析错误
79+
80+
我们建议将这种方式仅用于查询接口,如果你不需要这种文档/验证,你完全可以不使用它,而是使用更加开放的统一响应模型 ResponseModel
81+
82+
## 统一返回方法
83+
84+
`response_base` 是我们做的全局基础响应实例,此实例包含三个开放式方法,分别为:`success()``fail()``fast_seccess()`
85+
86+
::: warning
87+
它们都是同步方法,而不是异步。因为这些返回方法并不涉及 io 操作,所以,定义为异步,不但没有性能提升,反而增加了异步协程的开销
88+
:::
89+
90+
### success()
91+
92+
此方法通常作为默认响应方法使用,默认返回信息如下
93+
94+
```json
95+
{
96+
"code": 200,
97+
"msg": "请求成功",
98+
"data": null
99+
}
100+
```
101+
102+
### fail()
103+
104+
此方法通常在接口响应信息为失败时使用,默认返回信息如下
105+
106+
```json
107+
{
108+
"code": 200,
109+
"msg": "请求成功",
110+
"data": null
111+
}
112+
```
113+
114+
### fast_success()
115+
116+
此方法通常仅用于接口返回大型 json 时,可为 json 解析性能带来质的提升,默认返回信息如下
117+
118+
```json
119+
{
120+
"code": 200,
121+
"msg": "请求成功",
122+
"data": null
123+
}
124+
```

docs/guide/reference/socketio.md

Lines changed: 0 additions & 5 deletions
This file was deleted.

docs/sponsors.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22
title: 成为 FBA 的赞助者
33
---
44

5+
> [!TIP]
6+
> 此仓库作为模板库公开,任何个人或企业均可免费使用!
7+
58
::: note 前言
69
FBA 是一款基于 FastAPI 框架的后端架构解决方案,遵循伪三层架构设计,支持 Python 3.10 及以上版本。自 2023/04/07
710
启,我们一直致力于持续更新和维护,为此,我们投入了大量的时间和无限的热爱

0 commit comments

Comments
 (0)