93 lines
2.9 KiB
Markdown
93 lines
2.9 KiB
Markdown
# 路由注册
|
|
|
|
路由注册是将模块的 Endpoint 挂载到应用的过程。所有模块的路由在 `src/api/v1/router.py` 中统一注册。
|
|
|
|
## 文件位置
|
|
|
|
```
|
|
src/api/v1/router.py
|
|
```
|
|
|
|
## 注册步骤
|
|
|
|
### 第一步：导入路由
|
|
|
|
在 `router.py` 文件顶部的导入区域添加：
|
|
|
|
```python
|
|
from api.v1.endpoints.position import router as position_router
|
|
```
|
|
|
|
### 第二步：挂载路由
|
|
|
|
在 `register_router()` 函数中添加：
|
|
|
|
```python
|
|
v1.include_router(position_router, prefix="/position", tags=["岗位管理"])
|
|
```
|
|
|
|
| 参数 | 说明 |
|
|
|:----|:----|
|
|
| `position_router` | Endpoint 文件中创建的 `APIRouter` 实例 |
|
|
| `prefix="/position"` | 路由前缀，最终路径为 `/api/v1/position/xxx` |
|
|
| `tags=["岗位管理"]` | Swagger 文档中的分组标签 |
|
|
|
|
### 完整上下文
|
|
|
|
```python
|
|
# router.py 中的路由注册（简化示例）
|
|
|
|
from api.v1.endpoints.position import router as position_router
|
|
from api.v1.endpoints.level import router as level_router
|
|
from api.v1.endpoints.dept import router as dept_router
|
|
# ... 其他模块导入
|
|
|
|
def register_router(app):
|
|
# 认证相关路由（免登录）
|
|
app.include_router(auth_router, prefix="/api", tags=["认证管理"])
|
|
|
|
# 业务模块路由（需登录）
|
|
v1.include_router(position_router, prefix="/position", tags=["岗位管理"])
|
|
v1.include_router(level_router, prefix="/level", tags=["职级管理"])
|
|
v1.include_router(dept_router, prefix="/dept", tags=["部门管理"])
|
|
# ... 其他模块注册
|
|
|
|
# v1 路由组挂载到应用，带 login_required 中间件
|
|
app.include_router(v1, prefix="/api/v1")
|
|
```
|
|
|
|
## 最终 API 路径
|
|
|
|
注册后，Position 模块的接口路径为：
|
|
|
|
| 方法 | 路径 | 说明 |
|
|
|:----|:----|:----|
|
|
| GET | `/api/v1/position/page` | 分页查询 |
|
|
| GET | `/api/v1/position/detail/{id}` | 详情查询 |
|
|
| GET | `/api/v1/position/list` | 列表查询 |
|
|
| POST | `/api/v1/position/add` | 新增 |
|
|
| PUT | `/api/v1/position/update` | 更新 |
|
|
| DELETE | `/api/v1/position/delete/{id}` | 单条删除 |
|
|
| DELETE | `/api/v1/position/batchDelete` | 批量删除 |
|
|
| PUT | `/api/v1/position/status` | 状态变更 |
|
|
|
|
## prefix 命名规范
|
|
|
|
| 规则 | 示例 |
|
|
|:----|:----|
|
|
| 使用小写英文 | `/position` 而非 `/Position` |
|
|
| 使用单数形式 | `/position` 而非 `/positions` |
|
|
| 多单词用驼峰或短横线 | `/jobLog` 或 `/job-log` |
|
|
| 与模块目录名一致 | `modules/system/position/` → `/position` |
|
|
|
|
## 开发要点
|
|
|
|
1. **只需两行代码**：一行导入，一行注册
|
|
2. **prefix 与模块目录名保持一致**：便于代码导航
|
|
3. **tags 使用中文**：方便在 Swagger 文档中识别
|
|
4. **所有业务路由都挂在 `v1` 路由组下**：自动享受 `login_required` 认证保护
|
|
|
|
## 总结
|
|
|
|
路由注册在 `src/api/v1/router.py` 中统一管理，`prefix` 与模块目录名保持一致，`tags` 使用中文方便 Swagger 识别。所有业务路由挂在 `v1` 路由组下，自动享受 `login_required` 认证保护。
|