小蚂蚁云

文章管理

文章管理模块支持富文本编辑、分类关联、封面图片上传、图集管理等功能。适用于新闻、公告、帮助文档等内容管理场景。本模块是典型的「带文件处理」业务模块，涵盖了封面迁移、图集处理、富文本 XSS 清洗等核心机制。

模块结构

src/modules/article/
├── models.py     # 文章模型
├── schemas.py    # 表单验证
├── repository.py # 数据访问层
└── service.py    # 业务逻辑层（自定义，非 BaseService 子类）

自定义 Service

文章模块因涉及文件处理、富文本清洗、图集解析等复杂逻辑，未继承 BaseService，而是编写自定义 service 函数。这是项目中复杂模块的典型写法，与简单模块（如 Param 继承 BaseService）形成对比。

文章模型

python

# src/modules/article/models.py
class Article(base_model, base_db):
    """文章模型类"""
    __tablename__ = DB_PREFIX + "article"
    __table_comment__ = "文章表"

    # 分类ID
    category_id = Column(Integer, nullable=True, index=True, comment="分类ID")
    # 文章标题
    title = Column(String(150), nullable=True, index=True, comment="文章标题")
    # 文章封面（存相对路径，如 /article/20260907/xxx.png）
    cover = Column(String(255), nullable=True, comment="文章封面")
    # 文章图集（逗号分隔的相对路径，如 /article/20260907/a.png,/article/20260907/b.png）
    images = Column(Text, nullable=True, comment="文章图集")
    # 文章导读
    intro = Column(String(255), nullable=True, comment="文章导读")
    # 文章内容（富文本 HTML，图片地址存为 [IMG_URL] 占位符 + 相对路径）
    content = Column(Text, nullable=True, comment="文章内容")
    # 文章作者
    author = Column(String(100), nullable=True, comment="文章作者")
    # 状态：0-正常 1-下架
    status = Column(Integer, default=0, server_default=text('0'), nullable=False, index=True,
                    comment="文章状态：0-正常 1-下架")
    # 点击量
    click = Column(Integer, default=0, server_default=text('0'), nullable=False, comment="文章点击率")
    # 排序
    sort = Column(Integer, default=0, server_default=text('0'), nullable=False, comment="文章排序")

其中 id、create_user、create_time、update_user、update_time、is_delete 由基类 base_model 自动提供。

表单验证

ArticleForm（新增/编辑）

python

class ArticleForm(BaseForm):
    categoryId: Optional[int] = Field(None, ge=0, description="分类ID")
    title: str = Field(..., min_length=1, max_length=150, description="文章标题")
    cover: Optional[str] = Field(None, max_length=255, description="文章封面")
    images: Optional[str] = Field(None, description="文章图集")
    intro: Optional[str] = Field(None, max_length=255, description="文章导读")
    content: Optional[str] = Field(None, description="文章内容")
    author: Optional[str] = Field(None, max_length=100, description="文章作者")
    status: int = Field(0, ge=0, le=1, description="文章状态：0-正常 1-下架")
    click: int = Field(0, ge=0, le=2147483647, description="文章点击率")
    sort: int = Field(0, ge=0, le=99999, description="文章排序")

字段	必填	约束	说明
`categoryId`	否	`ge=0`	关联分类表，0 或不传表示无分类
`title`	是	`1~150 字符`	文章标题，唯一业务标识
`cover`	否	`max_length=255`	封面图片的临时 URL 或相对路径
`images`	否	无长度限制	图集，逗号分隔的 URL 字符串
`intro`	否	`max_length=255`	文章导读/摘要
`content`	否	无长度限制	富文本 HTML 内容
`author`	否	`max_length=100`	文章作者
`status`	否	`0~1`	默认 0（正常），1 为下架
`click`	否	`0~2147483647`	点击量，前端通常不传
`sort`	否	`0~99999`	排序号，值越大越靠前

ArticleStatusForm（状态变更）

python

class ArticleStatusForm(BaseModel):
    id: int = Field(..., gt=0, description="文章ID")
    status: int = Field(..., ge=0, le=1, description="文章状态：0-正常 1-下架")

用于独立的状态变更接口，只需传 id 和 status。

文件处理机制

文章模块涉及三类文件字段，处理方式各不相同：

处理流程总览

前端上传临时文件 → 获得临时 URL（如 /temp/20260907/xxx.png）
    ↓
提交表单（cover / images / content 携带临时 URL）
    ↓
后端 service 调用 save_file / save_content
    ↓
临时文件迁移到正式目录（如 /article/20260907/xxx.png）
    ↓
数据库存相对路径（不存完整 URL）
    ↓
查询时调用 get_file_url 拼接完整访问地址

1. 封面图片（cover）— `save_file`

python

# 新增时
cover = save_file(data.cover, "article") if data.cover else None

save_file(url, directory) 的处理逻辑：

将前端传来的 URL 还原为磁盘绝对路径
若文件在临时目录（temp/），移动到正式目录（upload/article/日期/）
若文件已在正式目录，直接返回相对路径
返回相对路径存入数据库（如 /article/20260907/xxx.png）
远程 URL（非本站文件）不处理，返回空字符串

防路径穿越

save_file 内部会校验磁盘真实路径必须位于 UPLOAD_DIR 内，防止 ../ 路径穿越攻击。

2. 图集（images）— `_build_images` / `_parse_images`

图集在数据库中存储为逗号分隔的相对路径字符串：

/article/20260907/a.png,/article/20260907/b.png,/article/20260907/c.png

写入时（_build_images）：

python

def _build_images(images):
    """逗号分隔的临时 URL → 逐个 save_file 迁移 → 逗号分隔的相对路径"""
    if not images:
        return None
    saved = []
    for url in images.split(','):
        url = url.strip()
        if not url:
            continue
        img = save_file(url, "article")
        saved.append(img or url)
    return ','.join(saved)

读取时（_parse_images）：

python

def _parse_images(images):
    """逗号分隔的相对路径 → 逐个 get_file_url 拼接 → 完整 URL 数组"""
    if not images:
        return []
    return [get_file_url(img) for img in images.split(',') if img]

前端拿到的是 URL 数组，可直接用于 <img> 渲染。

3. 富文本内容（content）— `save_content`

python

# 新增时
content = save_content(data.content, data.title, "article") if data.content else None

save_content(content, title, directory) 的处理流程：

原始 HTML
    ↓
① bleach 白名单清洗（移除 <script>/<iframe> 等危险标签和事件属性）
    ↓
② CSS 表达式过滤（移除 style 中的 expression()、javascript: 等向量）
    ↓
③ 提取 <img src="..."> 中的临时图片 URL
    ↓
④ 逐个调用 save_file 迁移到正式目录
    ↓
⑤ 将 HTML 中的图片 src 替换为正式相对路径
    ↓
⑥ 图片 alt 属性设置为文章标题（HTML 转义防注入）
    ↓
⑦ 将正式 URL 中的 FASTAPI_FILE_URL 前缀替换为 [IMG_URL] 占位符存库

为什么用 [IMG_URL] 占位符？

数据库中不存完整 URL（如 http://localhost:8031/upload/article/...），而是存 [IMG_URL]/article/...。查询详情时再将 [IMG_URL] 替换为实际的 FASTAPI_FILE_URL。这样更换域名或端口时无需批量更新数据库。

查询分页

过滤条件

参数	类型	说明
`title`	模糊搜索	文章标题，使用 `LIKE %keyword%`
`category_id`	精确匹配	分类 ID
`status`	精确匹配	文章状态：0-正常 1-下架

排序规则

按 sort 降序 → id 降序（即排序号越大越靠前，同排序号时新文章在前）。

分页回退容错

python

# 若当前页超出末页（数据被并发删除），自动回退到第一页
if page > 1 and not article_list:
    page = 1
    count = query.count()
    article_list = query.limit(limit).offset(0).all()

当用户停留在第 N 页时，如果其他用户删除了大量数据导致第 N 页为空，系统自动回退到第一页，避免返回空列表。

序列化处理

分页列表中每条记录会额外处理：

python

data = item.to_dict()
# 1. 封面 URL 拼接
if data.get('cover'):
    data['cover'] = get_file_url(data['cover'])
# 2. 图集解析为数组
data['images'] = _parse_images(data.get('images'))
# 3. 状态名称（数据字典映射）
data['statusName'] = get_dict_label('article_status', item.status)

查询详情

详情接口额外处理：

python

data = article.to_dict()
# 富文本内容：[IMG_URL] 占位符替换为实际域名
data['content'] = (article.content or "").replace("[IMG_URL]", FASTAPI_FILE_URL)
# 封面 URL 拼接
if data.get('cover'):
    data['cover'] = get_file_url(data['cover'])
# 图集：images 保留原始路径，imagesList 存完整 URL 数组
data['imagesList'] = _parse_images(data.get('images'))
# 状态名称
data['statusName'] = get_dict_label('article_status', article.status)

images vs imagesList

详情接口同时返回 images（逗号分隔原始路径）和 imagesList（完整 URL 数组）。前端展示用 imagesList，编辑回填用 images。

新增文章

python

def add_article(request, data: ArticleForm):
    # 1. 处理封面：临时文件迁移到正式目录
    cover = save_file(data.cover, "article") if data.cover else None
    # 2. 处理图集：逗号分隔 URL 逐个迁移
    images = _build_images(data.images)
    # 3. 处理富文本：XSS 清洗 + 图片迁移 + 占位符替换
    content = save_content(data.content, data.title, "article") if data.content else None
    # 4. 插入数据库（排除表单中的原值，用处理后的值替代）
    article_repo.create(
        **data.model_dump(exclude={'id', 'cover', 'images', 'content'}),
        cover=cover, images=images, content=content,
        create_user=get_realname(request)
    )
    return R.ok(msg="添加成功")

关键设计

model_dump(exclude={'id', 'cover', 'images', 'content'}) 排除文件字段的原始值，再用处理后的值（cover/images/content）显式传入，避免临时 URL 直接存入数据库。

更新文章

更新逻辑比新增更复杂，核心难点是防空值覆盖：

python

def update_article(request, data: ArticleForm):
    # 1. ID 校验
    if not data.id or data.id <= 0:
        return R.failed("记录ID不能为空")
    article = article_repo.get_by_id(data.id)
    if not article:
        return R.failed("记录不存在")

    # 2. 构造更新数据（排除 id；跳过 None，避免未传字段把旧值覆盖为 NULL）
    updData = data.model_dump(exclude={'id'}, exclude_none=True)

    # 3. 默认值字段特殊处理
    for f in ('status', 'click', 'sort'):
        if f not in data.model_fields_set:
            updData.pop(f, None)

    # 4. 文件字段：仅显式提供时更新
    if data.cover is not None:
        updData['cover'] = save_file(data.cover, "article") if data.cover else None
    if data.images is not None:
        updData['images'] = _build_images(data.images) if data.images else None
    if data.content is not None:
        updData['content'] = save_content(data.content, data.title, "article") if data.content else None

    # 5. 更新数据库
    result = article_repo.update(data.id, updData)
    return R.ok(msg="更新成功") if result else R.failed("更新失败")

为什么需要 `exclude_none=True`？

前端编辑表单通常只传用户修改过的字段。未修改的字段可能为 None（Pydantic 可选字段默认值）。如果不跳过 None 值，会把数据库中的旧值覆盖为 NULL。

为什么需要 `model_fields_set` 判断？

status、click、sort 三个字段在 ArticleForm 中有默认值 0。即使前端不传，model_dump() 也会输出 status=0。如果直接更新，会把用户之前设置的状态（如 1 下架）意外覆盖为 0（正常）。

data.model_fields_set 记录了前端显式传入的字段集合。只有前端显式传了 status，才更新该字段。

python

# 前端传了 { id: 1, title: "新标题" }（未传 status）
# data.model_fields_set = {'id', 'title'}
# status 不在其中 → 从 updData 中移除 → 不覆盖旧值

文件字段的清空语义

前端传值	行为
`cover: "/temp/xxx.png"`	迁移临时文件，更新封面
`cover: ""`	清空封面（置为 `None`）
`cover: null` 或不传	保留旧封面不变

图集和富文本同理。

删除文章

python

def delete_article(article_id):
    return BaseService.batch_delete_with_r(article_repo, article_id)

复用 BaseService.batch_delete_with_r 静态方法，支持单个 ID 或逗号分隔的多个 ID。软删除（is_delete=1），不物理删除数据。

状态变更

python

def update_article_status(request, data: ArticleStatusForm):
    article = article_repo.get_by_id(data.id)
    if not article:
        return R.failed("记录不存在")
    result = article_repo.update(data.id, {
        "status": data.status,
        "update_user": get_realname(request),
        "update_time": datetime.now(tz=timezone.utc)
    })
    return R.ok(msg="设置成功") if result else R.failed("设置失败")

独立的状态变更接口，只更新 status 字段，不影响其他字段。

API 接口

接口	方法	权限节点	说明
`/api/v1/article/page`	GET	`sys:article:page`	分页查询（支持 title/category_id/status 过滤）
`/api/v1/article/detail/{id}`	GET	`sys:article:detail`	详情查询（含富文本 URL 还原）
`/api/v1/article/add`	POST	`sys:article:add`	新增文章（含文件迁移 + 富文本清洗）
`/api/v1/article/update`	PUT	`sys:article:update`	编辑文章（防空值覆盖）
`/api/v1/article/status`	PUT	`sys:article:status`	设置状态（正常/下架）
`/api/v1/article/delete/{id}`	DELETE	`sys:article:delete`	单条删除
`/api/v1/article/batchDelete`	DELETE	`sys:article:batchDelete`	批量删除

数据字典

文章模块使用以下数据字典（需在字典管理中配置）：

字典编码	用途	字典项示例
`article_status`	文章状态名称	0=正常, 1=下架

分页列表和详情接口通过 get_dict_label('article_status', item.status) 将状态值转换为中文名称，输出到 statusName 字段。

前端对接要点

封面上传

前端使用上传组件，先上传到临时目录获得临时 URL，提交表单时将临时 URL 传给后端：

javascript

// 上传成功后
form.cover = '/temp/20260907/abc.png'  // 临时 URL
// 提交表单时，后端自动迁移到正式目录

图集管理

图集为逗号分隔的 URL 字符串，前端通常用数组管理：

javascript

// 编辑回填：将逗号分隔字符串转为数组
form.imagesList = detail.imagesList  // 后端已解析为数组
// 提交时：将数组转为逗号分隔字符串
form.images = form.imagesList.join(',')

富文本编辑器

推荐使用 TinyMCE 或 wangEditor，注意：

编辑器上传图片也走临时目录，内容提交后后端统一迁移
详情接口返回的 content 已将 [IMG_URL] 替换为完整 URL，可直接渲染
编辑回填时，编辑器接收的是已还原的完整 HTML

总结

文章管理模块是项目中典型的「带文件处理」复杂业务模块，核心特点：

1. 自定义 Service：未继承 BaseService，文件处理/富文本清洗/图集解析均为自定义逻辑
2. 三类文件字段：封面（save_file）、图集（_build_images/_parse_images）、富文本（save_content）
3. 临时文件迁移：前端上传到临时目录 → 提交表单后后端迁移到正式目录
4. XSS 防护：富文本经 bleach 白名单清洗 + CSS 表达式过滤
5. [IMG_URL] 占位符：数据库不存完整域名，查询时动态替换，便于域名迁移
6. 防空值覆盖：exclude_none=True + model_fields_set 判断，避免未传字段覆盖旧值
7. 分页回退：并发删除导致当前页为空时，自动回退第一页
8. 数据字典：状态名称通过 get_dict_label 动态映射，不硬编码

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

📁 文件处理

🔧 核心工具

🧩 辅助工具

模块结构

文章模型

表单验证

ArticleForm（新增/编辑）

ArticleStatusForm（状态变更）

文件处理机制

处理流程总览

1. 封面图片（cover）— `save_file`

2. 图集（images）— `_build_images` / `_parse_images`

3. 富文本内容（content）— `save_content`

查询分页

过滤条件

排序规则

分页回退容错

序列化处理

查询详情

新增文章

更新文章

为什么需要 `exclude_none=True`？

为什么需要 `model_fields_set` 判断？

文件字段的清空语义

删除文章

状态变更

API 接口

数据字典

前端对接要点

封面上传

图集管理

富文本编辑器

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

模块结构 ​

文章模型 ​

表单验证 ​

ArticleForm（新增/编辑） ​

ArticleStatusForm（状态变更） ​

文件处理机制 ​

处理流程总览 ​

1. 封面图片（cover）— save_file ​

2. 图集（images）— _build_images / _parse_images ​

3. 富文本内容（content）— save_content ​

查询分页 ​

过滤条件 ​

排序规则 ​

分页回退容错 ​

序列化处理 ​

查询详情 ​

新增文章 ​

更新文章 ​

为什么需要 exclude_none=True？ ​

为什么需要 model_fields_set 判断？ ​

文件字段的清空语义 ​

删除文章 ​

状态变更 ​

API 接口 ​

数据字典 ​

前端对接要点 ​

封面上传 ​

图集管理 ​

富文本编辑器 ​

总结 ​

模块结构

文章模型

表单验证

ArticleForm（新增/编辑）

ArticleStatusForm（状态变更）

文件处理机制

处理流程总览

1. 封面图片（cover）— `save_file`

2. 图集（images）— `_build_images` / `_parse_images`

3. 富文本内容（content）— `save_content`

查询分页

过滤条件

排序规则

分页回退容错

序列化处理

查询详情

新增文章

更新文章

为什么需要 `exclude_none=True`？

为什么需要 `model_fields_set` 判断？

文件字段的清空语义

删除文章

状态变更

API 接口

数据字典

前端对接要点

封面上传

图集管理

富文本编辑器

总结