240 lines
7.3 KiB
Markdown
240 lines
7.3 KiB
Markdown
# Endpoint 层
|
|
|
|
Endpoint 层是 HTTP 接口层，负责定义路由、权限装饰器和请求参数绑定。每个业务模块对应一个 endpoint 文件，所有业务逻辑委托给 Service 层处理。
|
|
|
|
## 文件位置
|
|
|
|
```
|
|
src/api/v1/endpoints/position.py
|
|
```
|
|
|
|
## 完整代码
|
|
|
|
```python
|
|
from fastapi import APIRouter, Request
|
|
|
|
from modules.system.position.schemas import PositionForm, PositionStatusForm
|
|
from core.access_decorators import check_demo
|
|
from core.access_decorators import permission_required
|
|
from modules.system.position.service import position_service
|
|
|
|
from core import R
|
|
|
|
# ============================================================
|
|
# 创建路由实例
|
|
# ============================================================
|
|
router = APIRouter()
|
|
|
|
|
|
# ============================================================
|
|
# 查询分页数据
|
|
# ============================================================
|
|
@router.get('/page', summary='查询分页数据')
|
|
@permission_required("sys:position:page")
|
|
def page(request: Request):
|
|
"""
|
|
获取岗位分页列表
|
|
:param request: FastAPI请求对象
|
|
:return: 分页数据响应
|
|
"""
|
|
return position_service.get_page(request)
|
|
|
|
|
|
# ============================================================
|
|
# 查询岗位详情
|
|
# ============================================================
|
|
@router.get('/detail/{id}', summary='查询岗位详情')
|
|
@permission_required("sys:position:detail")
|
|
def detail(request: Request, id):
|
|
"""
|
|
根据岗位ID查询详细信息
|
|
:param request: FastAPI请求对象
|
|
:param id: 岗位ID（路径参数）
|
|
:return: 岗位详情数据
|
|
"""
|
|
return R.ok(data=position_service.get_detail(id))
|
|
|
|
|
|
# ============================================================
|
|
# 获取岗位列表
|
|
# ============================================================
|
|
@router.get('/list', summary='获取岗位列表')
|
|
@permission_required("sys:position:list")
|
|
def get_position_list(request: Request):
|
|
"""
|
|
获取所有岗位列表（无分页，用于下拉选择）
|
|
:param request: FastAPI请求对象
|
|
:return: 岗位列表数据
|
|
"""
|
|
return R.ok(data=position_service.get_position_list(request))
|
|
|
|
|
|
# ============================================================
|
|
# 添加岗位
|
|
# ============================================================
|
|
@router.post('/add', summary='添加岗位')
|
|
@permission_required("sys:position:add")
|
|
@check_demo
|
|
def add(request: Request, data: PositionForm):
|
|
"""
|
|
新增岗位
|
|
:param request: FastAPI请求对象
|
|
:param data: 岗位表单数据
|
|
:return: 添加结果响应
|
|
"""
|
|
return position_service.add(request, data)
|
|
|
|
|
|
# ============================================================
|
|
# 更新岗位
|
|
# ============================================================
|
|
@router.put('/update', summary='更新岗位')
|
|
@permission_required("sys:position:update")
|
|
@check_demo
|
|
def update(request: Request, data: PositionForm):
|
|
"""
|
|
更新岗位信息
|
|
:param request: FastAPI请求对象
|
|
:param data: 岗位表单数据（必须包含 id 字段）
|
|
:return: 更新结果响应
|
|
"""
|
|
return position_service.update(request, data)
|
|
|
|
|
|
# ============================================================
|
|
# 删除岗位
|
|
# ============================================================
|
|
@router.delete('/delete/{id}', summary='删除岗位')
|
|
@permission_required("sys:position:delete")
|
|
@check_demo
|
|
def delete(request: Request, id):
|
|
"""
|
|
根据ID删除单个岗位
|
|
:param request: FastAPI请求对象
|
|
:param id: 岗位ID（路径参数）
|
|
:return: 删除结果响应
|
|
"""
|
|
return position_service.delete(id)
|
|
|
|
|
|
# ============================================================
|
|
# 设置岗位状态
|
|
# ============================================================
|
|
@router.put('/status', summary='设置岗位状态')
|
|
@permission_required("sys:position:status")
|
|
@check_demo
|
|
def status(request: Request, data: PositionStatusForm):
|
|
"""
|
|
修改岗位状态（启用/禁用）
|
|
:param request: FastAPI请求对象
|
|
:param data: 状态表单数据
|
|
:return: 状态更新结果响应
|
|
"""
|
|
return position_service.update_status(request, data)
|
|
|
|
|
|
# ============================================================
|
|
# 批量删除岗位
|
|
# ============================================================
|
|
@router.delete('/batchDelete', summary='批量删除岗位')
|
|
@permission_required("sys:position:batchDelete")
|
|
@check_demo
|
|
async def batch_delete(request: Request):
|
|
"""
|
|
批量删除岗位（请求体需传入 ID 数组）
|
|
|
|
Request Body 示例:
|
|
[1, 2, 3] # 岗位ID数组
|
|
|
|
:param request: FastAPI请求对象
|
|
:return: 批量删除结果响应
|
|
"""
|
|
return await position_service.batch_delete(request)
|
|
```
|
|
|
|
## 代码解析
|
|
|
|
### 路由实例
|
|
|
|
```python
|
|
router = APIRouter()
|
|
```
|
|
|
|
每个 endpoint 文件创建一个独立的 `APIRouter` 实例，后续在 `router.py` 中统一注册。
|
|
|
|
### 装饰器说明
|
|
|
|
| 装饰器 | 作用 | 位置 |
|
|
|:----|:----|:----|
|
|
| `@router.get/post/put/delete` | 定义 HTTP 方法和路径 | 最外层 |
|
|
| `@permission_required("sys:position:page")` | RBAC 权限校验 | 路由装饰器之后 |
|
|
| `@check_demo` | 演示模式拦截（仅写操作） | 权限装饰器之后 |
|
|
|
|
**装饰器顺序必须严格遵守**：路由 → 权限 → 演示模式。顺序错误会导致功能异常。
|
|
|
|
### 权限字符串命名规范
|
|
|
|
```
|
|
sys:{module}:{action}
|
|
```
|
|
|
|
| 动作 | HTTP 方法 | 说明 |
|
|
|:----|:----|:----|
|
|
| `page` | GET | 分页查询 |
|
|
| `detail` | GET | 详情查询 |
|
|
| `list` | GET | 列表查询 |
|
|
| `add` | POST | 新增 |
|
|
| `update` | PUT | 更新 |
|
|
| `delete` | DELETE | 单条删除 |
|
|
| `batchDelete` | DELETE | 批量删除 |
|
|
| `status` | PUT | 状态变更 |
|
|
|
|
### request 参数
|
|
|
|
```python
|
|
def page(request: Request):
|
|
```
|
|
|
|
所有 endpoint 都接收 `request: Request` 参数，即使当前不直接使用。原因：
|
|
1. Service 层需要通过 `request.query_params` 读取分页参数
|
|
2. 中间件通过 `request.state` 传递用户信息
|
|
3. 保持接口一致性
|
|
|
|
### Pydantic 表单参数
|
|
|
|
```python
|
|
def add(request: Request, data: PositionForm):
|
|
```
|
|
|
|
`data: PositionForm` 声明为函数参数后，FastAPI 自动：
|
|
1. 从请求体读取 JSON
|
|
2. 解析为 `PositionForm` 实例
|
|
3. 执行 Pydantic 校验
|
|
4. 校验失败返回标准错误响应
|
|
|
|
### 响应封装
|
|
|
|
- **Service 返回 R 对象的**（如 `add`、`update`、`delete`）：直接 `return`
|
|
- **Service 返回原始数据的**（如 `get_detail`、`get_position_list`）：用 `R.ok(data=...)` 包装
|
|
|
|
### 批量删除的异步处理
|
|
|
|
```python
|
|
async def batch_delete(request: Request):
|
|
return await position_service.batch_delete(request)
|
|
```
|
|
|
|
`batch_delete` 端点必须是 `async def`，因为需要 `await parse_batch_ids(request)` 异步读取请求体。
|
|
|
|
## 开发要点
|
|
|
|
1. **endpoint 层不含业务逻辑**：仅做路由定义、权限校验和参数绑定
|
|
2. **装饰器顺序**：路由 → 权限 → 演示模式
|
|
3. **所有端点都需要 `request: Request` 参数**
|
|
4. **写操作必须加 `@check_demo`**：防止演示环境被修改
|
|
5. **批量删除端点必须是 `async def`**：异步读取请求体
|
|
|
|
## 总结
|
|
|
|
Endpoint 层是 HTTP 请求的入口，负责路由定义、权限校验和参数绑定，不含业务逻辑。装饰器顺序固定为路由 → 权限 → 演示模式，写操作必须加 `@check_demo`，批量删除端点必须是 `async def`。
|