以织码在线教育系统为例，拆解一篇资讯从后台发布、前台展示到附件下载的完整链路。
培训平台的官网少不了新闻资讯：产品更新、行业观点、客户案例、培训百科，都需要一个统一的内容入口。
看起来，这个模块只是"后台发文章，前台看文章"。真正落到业务中，却要回答几个具体问题：
- 文章和附件如何组织，才能复用已有的素材管理能力？
- 内容创建后，如何完成编辑、上下架、排序与批量调整？
- 阅读计数如何与运营展示值分开，避免影响数据复盘？
- 同一篇文章里的不同附件，能否分别设置下载门槛？
本文围绕 News 与 NewsAttachment 两个模型，梳理数据结构、三端接口以及下载链路。字段、接口与页面路径沿用原有模块说明；文中的并发控制、统计口径与安全检查属于实现建议，不代表已经完成源码核验。
一、先拆清对象：文章管内容，附件管关联与策略
资讯模块的核心不是把所有信息塞进一张表，而是分清三个对象的职责：
News 保存文章，NewsAttachment 保存文章与素材的关联，Material 承接文件资源。
图 1：将文章内容、附件关联和文件资源分开，便于复用素材管理能力。
1. 文章模型：管理内容与展示信息
News 对应表 news，主要字段如下：
| 字段 | 含义 | 设计关注点 |
|---|---|---|
newsTitle |
标题 | 清楚表达内容主题 |
newsDesc |
摘要／描述 | 为列表页提供阅读预期 |
newsContent |
富文本正文 | 承载文章内容 |
newsLogo |
封面图 | 用于列表及详情的视觉展示 |
countRead |
业务阅读计数 | 统计口径由计数逻辑决定 |
countVirtualRead |
虚拟阅读基准 | 与业务计数分开维护 |
publishTime |
发布时间 | 支撑发布时间展示及相关查询 |
statusId / sort |
状态与排序 | 管理内容的可见性和展示顺序 |
标题、摘要、封面负责"让用户知道值不值得点开"，正文负责"点开后能获得什么"。这些字段应当协同编辑，而不是只填正文、其余随意留空。
2. 附件模型：管理归属、资源与下载门槛
NewsAttachment 的主要字段如下：
| 字段 | 含义 | 设计关注点 |
|---|---|---|
newsId |
所属文章 | 建立文章与附件的归属关系 |
materialId |
关联素材 | 复用统一的 Material 资源体系 |
loginRequired |
下载是否要求登录 | 按附件关联记录设置访问门槛 |
sort / statusId |
排序与状态 | 管理附件的展示顺序及可用状态 |
这里有两个值得保留的设计。
第一，复用素材，而不是为资讯再建一套文件管理 。资讯模块通过 materialId 关联文件，上传、存储、下载及资源保护应与统一素材体系衔接；具体具备哪些保护能力，需要结合素材模块实现确认。
第二，下载策略落在附件关联上。同一篇文章可以同时包含公开资料和登录后才能获取的资料。例如，课程介绍 PDF 可以公开下载，配套学习资料可以要求登录。
需要区分的是：loginRequired 只表达"是否需要登录"，并不自动等于"具备课程权限"或"属于指定角色"。如果资料需要更细的授权，还要补充相应规则。
二、接口为什么分三端：生产、浏览、鉴权各有边界
资讯模块把访问入口分为管理端、公开端和登录端。拆分的价值在于让不同调用方的职责和权限更清楚。
| 控制器 | 路径前缀 | 主要职责 |
|---|---|---|
AdminNewsController |
/resource/admin/news |
内容生产与运营管理 |
ApiNewsController |
/resource/api/news |
公开检索、详情浏览与公开附件下载 |
AuthNewsController |
/resource/auth/news |
登录附件下载入口 |
图 2：三类入口围绕同一份资讯数据工作，接口分层需要配合服务端权限校验。
1. 管理端：覆盖内容维护的主要动作
以下接口均以 /resource/admin/news 为前缀：
| 方法与相对路径 | 用途 |
|---|---|
POST /save |
创建资讯 |
PUT /edit |
编辑资讯 |
GET /page |
分页查询管理列表 |
GET /view |
查看管理详情 |
PUT /update/status |
调整单篇资讯状态 |
PUT /batch/status |
批量调整资讯状态 |
PUT /sort |
调整排序 |
DELETE /delete |
删除资讯 |
对应的管理端页面为：
- 列表页：
views/common/news/index.vue - 编辑页：
views/common/news/update/index.vue
页面放在 common 目录下，体现出资讯属于官网内容管理的一部分，与公告、幻灯等内容入口共同服务站点运营。
对运营来说，批量状态调整尤其有用：专题结束、资料过期或内容整改时，可以一次处理多篇文章。需要注意，批量操作也应逐项校验权限和状态规则，不能因为合并了请求就绕过单篇操作的限制。
2. 公开端：服务无需登录的内容浏览
以下接口均以 /resource/api/news 为前缀：
| 方法与相对路径 | 用途 |
|---|---|
GET /search |
分页检索资讯列表 |
GET /view |
查看资讯详情，并按现有说明触发阅读计数 |
GET /attachment/download |
公开附件下载入口 |
Web 端对应页面为 pages/news/list.vue 和 pages/news/detail.vue。
公开入口需要关注可见性边界：文章在后台存在，不代表可以对外访问。实现时应核对列表、详情和下载接口是否采用一致的发布可见规则，避免出现"列表看不到，下架文章却能通过详情链接访问"的情况。
3. 登录端：为受限附件提供下载入口
AuthNewsController 提供 /attachment/download 入口，完整路径为 /resource/auth/news/attachment/download。原有说明未明确该入口的 HTTP 方法，这里不额外推定。
按附件策略选择不同入口，能够让前端交互更清楚；真正的访问控制仍然要由服务端完成。下面单独展开这条链路。
三、附件下载：先检查策略，再交付资源
附件下载最容易出现的误区，是把"前端跳转到登录接口"当成完整的权限控制。
前端可以决定显示"下载"还是"登录后下载"，但调用方也可以直接构造请求。因此，服务端应根据附件记录判断访问条件，而不是相信调用方选择的路径。
图 3：建议的下载检查顺序。公开入口也必须拒绝绕过登录要求的请求。
一条完整的下载链路，建议至少检查以下内容：
- 查询附件及其所属文章：确认记录存在、关联正确，并符合对外可见规则。
- 读取服务端保存的
loginRequired：不能直接信任请求参数中传来的下载策略。 - 按策略校验会话：要求登录时验证会话；如另有课程、角色或组织限制，继续执行相应授权。
- 调用素材体系交付资源：按素材模块的规则返回文件、下载地址或临时访问凭证。
还要留意底层文件地址。如果受限附件最终指向一个长期公开可用的直链，即使接口层校验了登录，文件仍可能被绕过接口访问。资源交付方式需要与附件的访问策略一致。
四、阅读量：分开存储，更要说清统计口径
countRead 与 countVirtualRead 分开保存，能够避免运营调整值直接混入业务计数。
按原有模块说明，展示关系为：
text
展示阅读量 = countRead（业务阅读计数）
+ countVirtualRead（虚拟阅读基准）这个公式解决的是字段分离问题，并不能自动保证"展示值等于实际阅读"。虚拟基准属于运营调整，不能作为真实用户阅读的证据；分析报表和对外说明都应清楚区分口径。
1. 详情请求次数，不一定等于真实阅读人数
如果每次调用详情接口都累加，那么刷新页面、重复访问、自动预取或爬虫访问都有可能影响计数。countRead 即使不包含虚拟值，也不必然等于独立访客数，更不代表有效阅读人数。
| 指标 | 可以说明什么 | 不能直接推导什么 |
|---|---|---|
| 详情访问累计 | 被计数的详情访问次数 | 去重后的读者人数 |
| 按规则去重的访问 | 指定周期与规则下的访问规模 | 用户实际读完文章 |
| 虚拟阅读基准 | 运营设置的展示调整值 | 真实访问或内容效果 |
实际采用哪一种统计方式，应以业务需求和实现逻辑为准。做数据复盘时，应排除 countVirtualRead，并注明 countRead 是否去重、如何去重。
2. 并发累加要避免丢失更新
如果实现采用"先读取，再加一，再写回"，两个并发请求可能读取到同一个旧值，最终只增加一次。
对于数据库直接计数的方案，可以考虑原子递增。下面是实现思路示例，不代表项目中的实际 SQL 或字段命名：
sql
UPDATE news
SET count_read = count_read + 1
WHERE id = :newsId;使用这一思路的前提是明确字段默认值、资讯可见性校验，以及"哪些访问应该被计数"。访问量较大时，再评估缓存计数、异步汇总等方案，不必一开始就引入复杂机制。
五、跨服务读取：通过接口复用资讯能力
原有说明中，FeignNewsController 承担跨服务读取职责。其他服务如果需要使用资讯数据，可以通过服务接口调用，减少直接跨库查询带来的耦合。
例如，其他业务页面需要显示最新动态时，可以复用资讯查询能力，而不是重复维护一份资讯表。
这里不根据控制器名称推定它一定部署在哪个服务中：具体服务归属、调用方和可访问的数据范围，应以项目配置及实现为准。接口复用的重点，是让资讯能力有稳定边界，并统一处理数据可见性。
六、运营场景：让字段与接口真正服务内容
| 场景 | 可以使用的能力 | 需要关注的问题 |
|---|---|---|
| 产品更新与新品发布 | 封面、摘要、正文、发布时间 | 列表信息是否准确，阅读预期是否清楚 |
| 白皮书与资料传播 | 附件关联及登录下载策略 | 选择公开或登录获取；登录本身不等于已完成线索采集 |
| 专题调整与内容整改 | 批量状态调整 | 调整后列表、详情和下载是否同步受控 |
| 内容效果复盘 | 业务阅读计数与虚拟基准分离 | 排除虚拟值，注明去重和统计规则 |
| 多业务入口展示动态 | 跨服务读取接口 | 统一可见规则，避免各处重复维护 |
总结：把内容、计数和权限做成清楚的边界
一个可靠的新闻资讯模块，价值不只在"能发布文章"，还在于日常运营中的行为可解释、可维护。
- 数据层 ：
News管内容，NewsAttachment管关联与附件策略，Material承接文件资源。 - 接口层：管理端负责内容维护，公开端负责浏览，登录端提供受限附件下载入口。
- 统计层：业务计数与虚拟基准分开维护，数据分析明确采用什么口径。
- 权限层：以服务端保存的策略为准，让文章可见性、下载鉴权和资源交付保持一致。
对于织码在线教育系统而言，这样的拆分让资讯模块既能承担官网内容发布，也能衔接资料分发与跨服务展示。后续扩展时，沿着这些边界补充能力，比把所有逻辑堆进一个详情接口更容易维护。