Skip to content

Commit b8d6163

Browse files
authored
Improve incorrect usage in docs (#89)
* Improve incorrect usage in docs * Fix lint
1 parent 8444246 commit b8d6163

File tree

8 files changed

+130
-129
lines changed

8 files changed

+130
-129
lines changed

README.md

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,10 +4,20 @@
44

55
## Download
66

7+
### pip
8+
79
```shell
810
pip install sqlalchemy-crud-plus
911
```
1012

13+
### uv
14+
15+
```shell
16+
uv pip install sqlalchemy-crud-plus
17+
#
18+
uv add sqlalchemy-crud-plus
19+
```
20+
1121
## 文档
1222

1323
[SQLAlchemy CRUD Plus](https://fastapi-practices.github.io/sqlalchemy-crud-plus)
@@ -18,4 +28,4 @@ pip install sqlalchemy-crud-plus
1828

1929
## 赞助
2030

21-
如果此项目能够帮助到你,你可以赞助作者一些咖啡豆表示鼓励:[:coffee: Sponsor :coffee:](https://wu-clan.github.io/sponsor/)
31+
如果这个项目对你有帮助,欢迎[请作者喝杯咖啡](https://wu-clan.github.io/sponsor/)

docs/advanced/filter.md

Lines changed: 1 addition & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -219,7 +219,7 @@ class UserRole(Base):
219219

220220
```python
221221
# 创建
222-
user_role_data = {"user_id": 1, "role_id": 2}
222+
user_role_data = UserRoleCreate(user_id=1, role_id=2)
223223
user_role = await user_role_crud.create_model(session, user_role_data)
224224

225225
# 查询(使用元组)
@@ -283,8 +283,3 @@ recent_users = await user_crud.select_models(
283283
3. **性能考虑**: 为常用过滤字段创建数据库索引
284284
4. **OR 查询**: 过多 OR 条件可能影响性能,合理使用
285285
5. **通配符**: 避免以通配符开头的 LIKE 查询
286-
287-
## 下一步
288-
289-
- [关系查询](relationship.md) - 学习表关系处理
290-
- [事务控制](transaction.md) - 掌握事务管理

docs/advanced/relationship.md

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ SQLAlchemy CRUD Plus 提供强大的关系查询功能,支持 ORM 关系预加
44

55
## 核心参数
66

7-
- **load_strategies** - 关系数据预加载策略(需要 ORM relationship)
8-
- **join_conditions** - JOIN 条件控制(支持有无 relationship)
9-
- **load_options** - 原生 SQLAlchemy 选项
7+
- `load_strategies` - 关系数据预加载策略(需要 ORM relationship)
8+
- `join_conditions` - JOIN 条件控制(支持有无 relationship)
9+
- `load_options` - 原生 SQLAlchemy 选项
1010

1111
## ORM 关系(有 relationship)
1212

@@ -32,7 +32,7 @@ class Post(Base):
3232
author: Mapped['User'] = relationship(back_populates='posts')
3333
```
3434

35-
**查询示例**
35+
查询示例:
3636

3737
```python
3838
# 预加载关系数据
@@ -70,7 +70,7 @@ class Post(Base):
7070
author_email: Mapped[str] = mapped_column(String(100), index=True)
7171
```
7272

73-
**查询示例**
73+
查询示例:
7474

7575
```python
7676
from sqlalchemy_crud_plus import JoinConfig
@@ -139,7 +139,7 @@ result = await user_crud.select_models(
139139

140140
#### join_on 参数
141141

142-
**join_on** 定义表之间的关联条件,支持:
142+
`join_on` 定义表之间的关联条件,支持:
143143

144144
1. 简单等值条件
145145
```python
@@ -271,7 +271,7 @@ for result in results:
271271
print(f"{user.name}: {post.title if post else 'No post'}")
272272
```
273273

274-
**多表关联**
274+
多表关联:
275275

276276
```python
277277
# 关联多个表,都包含在结果中
@@ -298,7 +298,7 @@ for post, user, category in results:
298298
print(f"{post.title} by {user.name} in {category.name if category else 'Uncategorized'}")
299299
```
300300

301-
**fill_result 默认行为**
301+
fill_result 默认行为:
302302

303303
```python
304304
# fill_result=False (默认) - 只返回主表数据
@@ -316,19 +316,19 @@ users = await user_crud.select_models(
316316
# users 只包含 User 实例
317317
```
318318

319-
**选择正确的使用方式**
319+
选择正确的使用方式:
320320

321-
- **只需要主表数据**:使用 `fill_result=False` (默认)
322-
- **需要关联表数据**:使用 `fill_result=True`
323-
- **复杂查询/自定义字段**:使用原生 `select()`
321+
- 只需要主表数据:使用 `fill_result=False` (默认)
322+
- 需要关联表数据:使用 `fill_result=True`
323+
- 复杂查询/自定义字段:使用原生 `select()`
324324

325325
### JOIN 类型说明
326326

327327
| 类型 | 说明 | 使用场景 |
328328
|---------|-----------------|----------------|
329329
| `inner` | INNER JOIN | 只返回两表都匹配的记录 |
330330
| `left` | LEFT JOIN | 返回左表所有记录,右表可为空 |
331-
| `outer` | FULL OUTER JOIN | 返回两表所有记录 |
331+
| `full` | FULL OUTER JOIN | 返回两表所有记录 |
332332

333333
## load_strategies
334334

@@ -509,25 +509,25 @@ users = await user_crud.select_models(
509509

510510
## 最佳实践
511511

512-
1. **根据场景选择方式**
512+
1. 根据场景选择方式
513513
- 有外键 + 标准关系 → 使用 `load_strategies`
514514
- 无外键或复杂条件 → 使用 `JoinConfig`
515515

516-
2. **关联查询获取多表数据**
516+
2. 关联查询获取多表数据
517517
- 使用原生 `select(Model1, Model2).join()` 获取多表数据
518518
- 构建字典结果用于 API 返回
519519
- `JoinConfig` 主要用于过滤,不直接返回关联表数据
520520

521-
3. **性能优化**
521+
3. 性能优化
522522
- 为关联字段添加索引
523523
- 预加载避免 N+1 查询
524524
- 合理选择 JOIN 类型
525525

526-
4. **字段命名**
526+
4. 字段命名
527527
- 主键关联:`user_id`(整数)
528528
- 业务字段关联:`user_email``customer_code`(语义化)
529529

530-
5. **错误处理**
530+
5. 错误处理
531531
- 检查关联字段是否有索引
532532
- 验证 JOIN 条件的正确性
533533
- 处理关联数据为空的情况

0 commit comments

Comments
 (0)