小蚂蚁云

文章管理

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

模块结构

src/modules/cms/article/
├── models.py     # 文章模型
├── schema.py     # 表单验证（WTForms）
├── repository.py # 数据访问层
├── service.py    # 业务逻辑层
└── router.py     # 路由控制器

Service 设计

文章模块涉及文件处理、富文本清洗、图集解析等复杂逻辑。可选择继承 BaseService 并覆写钩子方法，或编写独立的 service 函数。简单 CRUD 模块（如 Param、Position）继承 BaseService 即可。

文章模型

python

# src/modules/article/models.py
class Article(BaseModel, BaseDB):
    """文章模型类"""
    __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

# src/modules/cms/article/schema.py
from wtforms import StringField, IntegerField, TextAreaField
from wtforms.validators import DataRequired, Length, NumberRange, Optional
from src.common.forms.base_form import BaseForm


class ArticleForm(BaseForm):
    """文章创建/编辑表单"""
    categoryId = IntegerField('分类ID', validators=[Optional(), NumberRange(min=0)])
    title = StringField('文章标题', validators=[
        DataRequired(message='文章标题不能为空'),
        Length(max=150, message='文章标题长度不得超过150个字符')
    ])
    cover = StringField('文章封面', validators=[Optional(), Length(max=255)])
    images = StringField('文章图集', validators=[Optional()])
    intro = StringField('文章导读', validators=[Optional(), Length(max=255)])
    content = TextAreaField('文章内容', validators=[Optional()])
    author = StringField('文章作者', validators=[Optional(), Length(max=100)])
    status = IntegerField('文章状态', validators=[
        Optional(), NumberRange(min=0, max=1, message='文章状态值在0~1之间')
    ])
    sort = IntegerField('文章排序', validators=[
        Optional(), NumberRange(min=0, max=99999)
    ])

字段	必填	约束	说明
`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(BaseForm):
    """文章状态更新表单"""
    id = IntegerField('文章ID', validators=[
        DataRequired(message='文章ID不能为空'),
        NumberRange(min=1, message='文章ID必须大于0')
    ])
    status = IntegerField('文章状态', validators=[
        DataRequired(message='文章状态不能为空'),
        NumberRange(min=0, max=1, message='文章状态值在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 中的文件访问前缀替换为 [IMG_URL] 占位符存库

为什么用 [IMG_URL] 占位符？

数据库中不存完整 URL（如 http://localhost:8021/upload/article/...），而是存 [IMG_URL]/article/...。查询详情时再将 [IMG_URL] 替换为实际的文件访问 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]", 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(data: dict):
    """新增文章"""
    # 1. 表单校验
    form = ArticleForm(data=data)
    if not form.validate():
        raise BizError(regular.get_err(form))

    # 2. 处理封面：临时文件迁移到正式目录
    cover = save_file(form.data.get('cover'), "article") if form.data.get('cover') else None
    # 3. 处理图集：逗号分隔 URL 逐个迁移
    images = _build_images(form.data.get('images'))
    # 4. 处理富文本：XSS 清洗 + 图片迁移 + 占位符替换
    content = save_content(form.data.get('content'), form.data.get('title'), "article") if form.data.get('content') else None

    # 5. 插入数据库（用处理后的值替代原始值）
    ArticleRepository.create(
        category_id=form.data.get('categoryId'),
        title=form.data.get('title'),
        cover=cover,
        images=images,
        intro=form.data.get('intro'),
        content=content,
        author=form.data.get('author'),
        status=form.data.get('status', 0),
        sort=form.data.get('sort', 0),
        create_user=get_realname(),
        update_user=get_realname(),
    )

关键设计

文件字段（cover/images/content）经过处理后再传入 create()，避免临时 URL 直接存入数据库。非文件字段直接从表单数据中取值。

更新文章

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

python

def update_article(data: dict):
    """
    更新文章

    处理流程：
        1. ID 校验
        2. 表单校验
        3. 文件字段处理（仅显式提供时更新）
        4. 更新数据库
    """
    # 1. 表单校验
    form = ArticleForm(data=data)
    if not form.validate():
        raise BizError(regular.get_err(form))

    # 2. ID 校验
    article_id = form.data.get("id")
    if not article_id or int(article_id) <= 0:
        raise BizError("记录ID不能为空")
    article = ArticleRepository.get_by_id(article_id)
    if not article:
        raise BizError("记录不存在")

    # 3. 构造更新数据（过滤掉非模型字段）
    update_data = {}
    for key, value in form.data.items():
        if key in ('id', 'cover', 'images', 'content'):
            continue  # 文件字段单独处理
        if value is not None:
            update_data[key] = value

    # 4. 文件字段：仅前端显式传值时更新
    if form.data.get('cover') is not None:
        update_data['cover'] = save_file(form.data['cover'], "article") if form.data['cover'] else None
    if form.data.get('images') is not None:
        update_data['images'] = _build_images(form.data['images']) if form.data['images'] else None
    if form.data.get('content') is not None:
        update_data['content'] = save_content(form.data['content'], form.data.get('title'), "article") if form.data['content'] else None

    # 5. 更新数据库
    result = ArticleRepository.update_by_id(article_id, update_data)
    if not result:
        raise BizError("更新失败")

为什么需要跳过 None 值？

前端编辑表单通常只传用户修改过的字段。未修改的字段在请求体中可能为 null（JSON）或不存在。如果不跳过 None 值，会把数据库中的旧值覆盖为 NULL。因此只更新前端显式传入的非空字段。

文件字段的清空语义

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

图集和富文本同理。

删除文章

python

# 通过 BaseService 的 remove 方法实现批量软删除
delete_articles = ArticleService.remove

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

状态变更

python

def update_article_status(data: dict):
    """更新文章状态"""
    form = ArticleStatusForm(data=data)
    if not form.validate():
        raise BizError(regular.get_err(form))

    article_id = form.data.get("id")
    if not ArticleRepository.exists(article_id):
        raise BizError("记录不存在")

    result = ArticleRepository.update_status(article_id, form.data.get("status"))
    if not result:
        raise BizError("设置失败")

独立的状态变更接口，只更新 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. 文件处理：三类文件字段（封面 save_file、图集 _build_images/_parse_images、富文本 save_content）
2. 临时文件迁移：前端上传到临时目录 → 提交表单后后端迁移到正式目录
3. XSS 防护：富文本经 bleach 白名单清洗 + CSS 表达式过滤
4. [IMG_URL] 占位符：数据库不存完整域名，查询时动态替换，便于域名迁移
5. 防空值覆盖：更新时跳过 None 值，避免未传字段覆盖旧值
6. 分页回退：并发删除导致当前页为空时，自动回退第一页
7. 数据字典：状态名称通过 dict_utils 动态映射，不硬编码

🔐 认证与安全

📊 数据与配置

📝 日志与监控

🛡️ 防护与治理

🔄 事务管理

📁 文件处理

🔧 核心工具

🧩 辅助工具

模块结构

文章模型

表单验证

ArticleForm（新增/编辑）

ArticleStatusForm（状态变更）

文件处理机制

处理流程总览

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

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

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

查询分页

过滤条件

排序规则

分页回退容错

序列化处理

查询详情

新增文章

更新文章

为什么需要跳过 None 值？

文件字段的清空语义

删除文章

状态变更

API 接口

数据字典

前端对接要点

封面上传

图集管理

富文本编辑器

总结

Become a sponsor

企业级中台解决方案

企业级中台解决方案

模块结构 ​

文章模型 ​

表单验证 ​

ArticleForm（新增/编辑） ​

ArticleStatusForm（状态变更） ​

文件处理机制 ​

处理流程总览 ​

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

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

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

查询分页 ​

过滤条件 ​

排序规则 ​

分页回退容错 ​

序列化处理 ​

查询详情 ​

新增文章 ​

更新文章 ​

为什么需要跳过 None 值？ ​

文件字段的清空语义 ​

删除文章 ​

状态变更 ​

API 接口 ​

数据字典 ​

前端对接要点 ​

封面上传 ​

图集管理 ​

富文本编辑器 ​

总结 ​

模块结构

文章模型

表单验证

ArticleForm（新增/编辑）

ArticleStatusForm（状态变更）

文件处理机制

处理流程总览

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

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

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

查询分页

过滤条件

排序规则

分页回退容错

序列化处理

查询详情

新增文章

更新文章

为什么需要跳过 None 值？

文件字段的清空语义

删除文章

状态变更

API 接口

数据字典

前端对接要点

封面上传

图集管理

富文本编辑器

总结