主题
二、架构与工程纪律
本章速览:读完后你会知道 —— ① 代码为什么这样分层、模块边界靠什么守住;② 一次后台请求经过哪些拦截器与鉴权;③ 没有 MQ/Redis 时,幂等、调度与失败补偿靠什么;④ 隐私内容在离开进程前要过哪四道关;⑤ 新增功能必须同步哪些闸门。
2.1 分层与依赖规则
浏览器 ──HTTP──> Controller(参数/鉴权/返回 R) ──> Service(业务规则/事务)
├─> Mapper(MyBatis-Plus) ──> MySQL
├─> 其它模块的 Service 接口(同进程)
└─> SPI 端口(common.port.*)──> 具体实现
外部(DSH/桥/Hindsight)──HTTP──> 专用控制器(/api/agent/**,独立令牌拦截器)三条硬规则(都由测试或架构闸守住):
- Controller 不写业务:只做参数校验、身份提取、调用 Service、包装
R。 - 模块间只通过 Service 接口交互,禁止直接注入别的模块的 Mapper/Entity;
ModuleBoundaryTest扫描 import 与字段类型,越界即红。 - 跨模块能力用"端口"表达:
common/port与common/spi下的接口(FileStoragePort、EgressGatePort、MemoryHealthPort、MemoryVectorPort、JobRunnerPort、AuditPort、MediaReferenceProvider、JobLogRecorder等)由具体模块实现,调用方只依赖接口 —— 这样"记忆模块依赖向量化"不会反向导致 Spring 循环依赖(MemoryReadService的 javadoc 专门解释了这条)。
2.2 横切关注点落在哪
| 关注点 | 实现位置 | 说明 |
|---|---|---|
| 认证 / 授权 | framework/security/*Interceptor + AgentAuthInterceptor | 三套主体:后台用户(JWT)、Agent 令牌(scope)、API Key |
| 审计 | AuditAspect + @AuditLog 注解 | 自动记录操作人/动作/参数摘要/结果,写入 sys_audit_log |
| 异常 → 响应 | GlobalExceptionHandler | 业务错误回 200 + code;协议层错误回真实状态码(401/404/405/409/413) |
| 日期/时区 | TimezoneGuard + TimeConfig | JVM 固定 Asia/Shanghai;扩展平台时间存 UTC(见 4.6) |
| JSON/大整数 | JacksonConfig | Long 序列化为字符串,避免前端 JS 精度丢失(MCP 工具尤其致命) |
| 定时任务不可重入 | NonReentrantJobAspect + @NonReentrant | 单实例下防止 Job 与自己叠加;同时写入 sys_job_log |
| 请求级缓存/幂等 | TxHooks、DuplicateKeyException 捕获 | "先插唯一键抢占"是全项目的幂等范式 |
2.3 请求生命周期(一次后台请求发生了什么)
- IP 白名单(
AdminIpGuardInterceptor,仅/api/admin):不在白名单直接 403; 它先于 JWT 校验,因为登录接口也要受网络层兜底。 - 维护模式(
MaintenanceInterceptor):site.maintenance.enabled=1时,非白名单请求回维护提示。 - JWT(
AuthInterceptor):解析Authorization: Bearer,校验签名/过期/黑名单; 登录接口与健康检查/验证码等公开路径排除。/api/agent走另一套AgentAuthInterceptor(专用令牌 + IP 白名单 + 速率限制),两者互不混用。 - Controller:
@Validated校验 DTO;查询参数绑定失败由GlobalExceptionHandler转成 "参数 xxx 取值不合法"(不透出 Spring 异常原文)。 - Service:业务规则、事务(
@Transactional)、幂等键、事件发布(业务事件用@TransactionalEventListener(AFTER_COMMIT),避免"事务还没提交监听器就发通知")。 - 响应:
R<T>{code,message,data,success};success由R.isSuccess()派生(不是独立字段), Jackson 自动序列化。分页统一{records,total,current,size}。
错误语义约定:业务/参数/权限问题 → HTTP 200 + code(前端统一提示); 请求方式不对 → 405;资源不存在 → 404;未登录 → 401;课程/系列冲突 → 409; 上传超限 → 413。理由:监控与安全扫描需要协议层事实,业务错误再用 code 区分。
2.4 调度与后台任务模型
项目没有 MQ、没有分布式锁,调度靠两种机制:
| 机制 | 实现 | 适用 |
|---|---|---|
Spring @Scheduled | 27 个方法(附录 C);NonReentrantJobAspect 防叠加;每轮写 sys_job_log | Java 侧固定任务(清理、日报轮询、向量 GC、会话镜像…) |
| 扩展平台触发器 | ExtensionTriggerScheduler 每 30s 轮询 next_run_at(UTC),认领后异步执行 | 系统扩展与第三方插件的定时/手动/webhook 触发 |
约定:
- 单实例假设:限流、锁、缓存都是进程内;多实例会重复执行(
docs/全项目审查记录.md已把 "单实例"列为已知边界)。 - 重启不丢任务:Java 任务把"在跑但进程重启"的记录由
StaleJobLogReconciler标成失败并注明; 扩展运行靠 run identity +dedup_key幂等续跑;摄取/采集靠服务端水位。 - AI 调用不占调度线程:长任务(日报生成、扩展 agent 运行)提交到
aiExecutor/独立线程池, 避免把每分钟的日程提醒拖住(DailyDigestJob的 javadoc 专门解释)。 - 慢任务必须可见:每轮至少写一行 job log,写明"扫描 N / 处理 M / 跳过原因"; 失败写
fail与异常摘要。
2.5 数据与一致性纪律
| 纪律 | 具体做法 |
|---|---|
| 迁移只前进 | Flyway V{n}__描述.sql;生产 flyway_schema_history 与仓库逐文件一致(163/V163) |
| 无物理外键 | 逻辑引用列 + 应用层校验;删除走软删(deleted)或显式级联,避免迁移顺序与锁表地狱 |
| 唯一键做幂等 | 提醒 dedup_key、通知 dedup_key、摄取 (session_id,line_no)、扩展 run identity、订阅邮箱等 |
| 事务边界清晰 | Service 方法上 @Transactional;禁止在事务内做外部 HTTP(AI/微信/邮件都在提交后异步或监听器 AFTER_COMMIT) |
| 时间口径 | 业务时间用 Asia/Shanghai;扩展平台 next_run_at/last_run_at 存 UTC(UTC_TIMESTAMP() 判据) |
| ID | 雪花 ID(Long),对外 JSON 一律字符串化;MCP 参数兼容字符串/数字但回执用字符串 |
| 缓存 | 配置单键 30s 缓存(保存即失效);查询向量缓存 60s/LRU 512;不引入外部缓存 |
| 删除 | 内容类软删(可恢复);日志类按保留期物理删(*RetentionJob),清理前有引用反查防误删 |
2.6 隐私与出网(这个项目最在意的横切面)
内容分三级:public(门户可见)/ internal(仅博主与助手可见)/ private(不进模型上下文)。
四道防线:
- 数据层过滤:门户只读接口在 SQL 层强制
status=1、is_public=1;RAG 的访客版 (publicOnly=true)在 SQL 层排除私有笔记 —— 即使上层代码疏漏,私有内容也进不了检索结果。 - 出网台账(
EgressLedger):每次把内容交给模型/外部(chat、embed、上下文注入) 写一行ai_egress_log:场景、通道、各级条数、字节数,不记正文;写失败绝不抛异常(旁路数据)。 - 出网闸(
EgressGate):site.ai.egress三档normal/minimal/frozen; frozen 下 chat/embed/生图一律拒绝;读侧对未知值 fail-open 但打 warn(写侧已校验,见 6.2)。 - 可见性收窄:后台接口默认 admin-only;MCP 工具按 scope 校验;微信桥只服务白名单用户; 后台附件下载要求归属会话且
nosniff + inline。
2.7 安全设计速览
| 面 | 措施 |
|---|---|
| 登录 | bcrypt 密码、失败锁定、JWT 签名(COSMOS_JWT_SECRET)、登录日志与异地告警(sys_login_log) |
| Agent | 独立令牌文件(600 权限)、scope(memory/daily/mcp/ext)、IP 白名单、限速、审计到 agent_tool_call_log |
| 程序接入 | sys_api_key(前缀展示、哈希存储)+ /api/agent 白名单 |
| 访客写 | 验证码 → IP 频率限制 → 敏感词 → 审核开关(评论/留言/友链四层) |
| 上传 | 扩展名/MIME 白名单、大小上限、随机文件名、私有目录、下载时强制 X-Content-Type-Options: nosniff |
| 渲染 | 后端 MarkdownRenderer 输出 HTML 时做白名单清洗(escapeHtmlForImport 用于导入);门户 CSP script-src 'self' |
| 配置密钥 | SMTP 授权码/API Key 以 enc: 密文入库(CryptoUtil + COSMOS_SECRET_KEY),接口只回掩码 |
| 依赖/构建 | 前端依赖锁版本;md-editor 扩展走本地同源(避开 CSP 与 CDN) |
2.8 可观测性:让"没发生"也能被看见
| 账本/信号 | 写什么 | 怎么用 |
|---|---|---|
sys_job_log | 每个 Java 任务每轮:名字、状态、消息、耗时 | 后台"任务日志";能力健康看板的判据之一 |
notify_log / webhook_delivery | 每次投递:通道、状态、重试、响应摘要 | 排查"消息发没发";重试 Job 的对象 |
extension_run / _run_event / _capability_call / _policy_decision / _effect | 扩展运行全生命周期 | 扩展中心与运维看板的唯一事实来源 |
ai_egress_log / ai_token_usage | 出网台账、token 与成本 | 隐私审计、用量报表、熔断 |
proactive_log | 每条主动消息的去重键与结果 | 预算、反馈、夜间安静策略 |
心跳 sys_job_log 行(bridgeHeartbeat/chainProbe) | 外部进程存活与最后上报 | doctor.sh 与能力健康看板 |
/api/health、/api/health/ready | DB/Hindsight/桥/启动自检 | 监控与发布验证 |
doctor.sh(25 项) | 端口/挂载/令牌/备份/迁移/环回绑定… | 手动体检;发布后必跑 |
2.9 变更纪律:加东西之前先看这几条
- 加模块:
module_xxx/controller|service|mapper|entity,禁止 import 别的模块 mapper; 在docs与ConfigKeys/迁移里登记;跑ModuleBoundaryTest。 - 加端点:必须写进附录 L(文档检查器按源码注解逐条核对);无 UI 入口的要在 §8.4 登记。
- 加表/列:新迁移(不许改旧迁移);表名写进附录 M;实体加
@TableName。 - 加配置键:先写迁移种子(
INSERTsys_config),再用ConfigKeys常量读取;check-config-registry.mjs会核"键↔面板↔读点"三方一致。 - 加能力:
CapabilityCatalog登记(type/risk/dataClass/egress/systemOnly), 在DefaultCapabilityGateway实现,能力调用走审计网关。 - 加定时任务:
@Scheduled+@NonReentrant+ 每轮写sys_job_log;附录 C 同步。 - 改数字:改完先跑
mvn -B -o clean test,架构闸会告诉你文档哪里没同步。
2.10 架构闸:24 条规则在防什么
ArchitectureGuardTest 是"项目宪法"的可执行版本,24 条规则大致分五类:
| 类别 | 例子 |
|---|---|
| 分层/边界 | 业务模块不得互相依赖实现;扩展 runtime 不得直接依赖业务模块 |
| 纪律落地 | 业务事件监听器必须 AFTER_COMMIT;定时任务必须可重入保护;出网必须走网关 |
| 数字/清单 | 文档规模数字、表清单、迁移号、端点路径、配置键与源码一致 |
| 死代码 | 无注解/无接口/无引用的 public 方法;无引用的 @TableName 字段(逐条扫描) |
| 安全/文档 | 禁止硬编码密钥;代码引用的 docs/*.md 必须存在;MCP 工具清单一致 |