面向 AI Agent 的后端架构改造：从系统事实到无人值守开发

过去的后端架构主要围绕“人类工程师可维护”来设计：代码分层清晰、接口稳定、日志可查、监控完整、发布可回滚、故障可定位。这些原则仍然重要，但 AI Coding、Agentic Coding 进入工程现场后，后端系统还需要满足一个新的要求：它能不能被 AI Agent 正确理解、修改、验证和运维。

AI Friendly 不是多写几份 README，也不是单纯统一代码风格。它真正要解决的问题是：AI Agent 在上下文有限、权限有限、试错成本有限的条件下，能不能知道系统边界在哪里，能不能判断哪些代码能改、哪些不能改，能不能完成验证，能不能给出风险和回滚方案。

换句话说，过去建设的是“可维护系统”，以后还要建设“可被智能体维护的系统”。

大型后端系统尤其需要这层能力。一个互联网后端通常包含几十个甚至上百个微服务，还会连接关系型数据库（RDB）、Redis、消息队列、对象存储、搜索引擎、任务调度、配置中心、注册中心、网关、风控、权限、审计、灰度、监控、告警和数据仓库。经验丰富的工程师知道哪些接口有历史包袱，哪些字段不能改，哪个 Topic 还被老链路消费，哪个服务已经不适合承载新能力；AI Agent 不知道，它只能从代码、文档、日志、测试、运行环境和历史变更里推断。

所以，后端架构 AI Friendly 的核心，不是“让 AI 更聪明”，而是把藏在人脑、群聊、会议纪要和事故复盘里的系统知识，变成显式、结构化、可检索、可执行、可验证的工程资产。

flowchart TD
    A[隐性系统知识] --> B[结构化系统事实]
    B --> C[AI 可检索上下文]
    C --> D[受控 Harness 执行]
    D --> E[测试与策略校验]
    E --> F[生成 PR / 灰度 / 回滚方案]
    F --> G[审计与持续沉淀]

一、先建立 AI 能读懂的系统事实层

AI Agent 不能只靠搜索代码来理解系统。代码只能告诉它“现在怎么写”，却很难解释“为什么必须这么写”。大型后端系统要支持 AI 参与开发，需要先建立一层机器可读的系统事实。

这层事实至少包括六类内容。

这些事实合在一起，构成后端系统的 AI 理解底座。没有这层底座，AI Agent 只能做局部补代码；有了它，AI 才能参与跨服务开发、架构治理、排障修复和无人值守运维。

架构事实：给 AI 一张全局地图

架构事实负责描述系统为什么这样组织。它应该覆盖业务域划分、服务分层、核心链路、同步与异步边界、强弱依赖、数据所有权、灰度发布边界、故障隔离边界、历史遗留模块和目标架构方向。

如果没有架构事实，AI 很容易把局部修复做成全局破坏。例如：

• 把应该放在 BFF（Backend For Frontend，面向前端的后端服务）层的兼容逻辑写进核心领域服务；
• 把原本异步解耦的流程改成同步远程调用；
• 把只读依赖误判成可写依赖；
• 在核心交易链路里增加额外 RPC（Remote Procedure Call，远程过程调用）；
• 继续在已经标记为遗留的服务里增加新能力。

架构事实不是一张给人看的 PPT，而是要能被 AI 检索、被 CI（Continuous Integration，持续集成）校验、被 Harness 执行。

一个最小可用的 architecture.yaml 可以这样组织：

domains:
  order:
    owner: order-platform
    services:
      - order-service
      - order-query-service
    riskLevel: high

layers:
  gateway:
    allowDependsOn:
      - bff
  bff:
    allowDependsOn:
      - application
      - domain
  domain:
    allowDependsOn:
      - infrastructure

criticalPaths:
  createOrder:
    services:
      - api-gateway
      - order-bff
      - order-service
      - inventory-service
      - payment-service
    latencyBudgetMs: 800
    allowNewSyncDependency: false

dataOwnership:
  order_db.orders:
    ownerService: order-service
    writableBy:
      - order-service
    readableBy:
      - order-query-service

这类结构化文件的价值在于：AI 修改代码前，可以先判断需求属于哪个业务域、是否影响核心链路、是否违反分层规则、是否越权访问数据。

服务事实：每个微服务都需要 Service Card

在几十个微服务组成的系统里，AI 最怕的不是代码多，而是服务边界不清。边界不清会导致它改错服务、调用错接口、重复造轮子，甚至在错误层级解决问题。

每个微服务都应该有一张 Service Card，也可以叫 System Card。它不是普通 README，而是服务身份证。

service:
  name: order-service
  domain: order
  layer: domain
  riskLevel: high
  owner: order-platform

responsibilities:
  - 创建订单
  - 管理订单状态流转
  - 维护订单主表和订单明细
  - 发布订单领域事件

notResponsibilities:
  - 不直接处理支付渠道回调
  - 不直接扣减库存
  - 不对客户端暴露聚合接口

entities:
  - Order
  - OrderItem
  - OrderStatus

ownedTables:
  - order_db.orders
  - order_db.order_items

apis:
  - name: CreateOrder
    protocol: RPC
    idempotent: true
    callers:
      - order-bff
    compatibility: backward-compatible

messages:
  produces:
    - topic: order.created
      idempotencyKey: orderId
  consumes:
    - topic: payment.succeeded
      idempotencyKey: paymentId

dependencies:
  strong:
    - inventory-service
  weak:
    - coupon-service
    - notification-service

tests:
  unit: mvn test -pl order-service
  contract: mvn test -Pcontract
  integration: mvn verify -Pintegration

release:
  canary: true
  rollback: "通过发布平台回滚镜像；数据库变更需执行 rollback.sql"

Service Card 应该放在服务仓库根目录，并由 CI 检查必填字段是否完整。更好的做法是部分自动生成：接口从 IDL（Interface Definition Language，接口定义语言）或 OpenAPI 生成，依赖从调用链和配置生成，表结构从 Schema 生成，监控链接从服务注册信息生成。人工主要维护业务解释、边界约束和历史注意事项。

二、Architecture Map：让 AI 先看懂系统，而不是某个仓库

小系统只有几个服务时，AI 通过代码搜索和 README 也许能推断结构。大型分布式系统不行，因为复杂性主要不在单个服务内部，而在服务之间的关系。

AI 需要知道：

• 哪些服务属于核心交易链路，哪些只是后台运营系统；
• 哪些调用是强依赖，哪些可以降级；
• 哪些流程是同步链路，哪些流程靠异步事件推进；
• 哪些数据库属于服务私有，哪些数据通过事件同步；
• 哪些系统是目标架构方向，哪些系统只是历史遗留；
• 哪些服务可以承载新需求，哪些服务只能维护不再扩展。

Architecture Map 的目标不是画得漂亮，而是让 AI 在进入任何一个服务、修改任何一段代码之前，先建立系统级方向感。

flowchart LR
    Client[客户端] --> Gateway[网关层]
    Gateway --> BFF[BFF 层]
    BFF --> Order[订单领域服务]
    BFF --> User[用户领域服务]
    Order --> Inventory[库存服务]
    Order --> Payment[支付服务]
    Order --> MQ[(消息队列)]
    Payment --> MQ
    MQ --> Fulfillment[履约服务]
    MQ --> Notify[通知服务]
    Order --> OrderDB[(订单库)]
    Inventory --> InventoryDB[(库存库)]
    Payment --> PaymentDB[(支付库)]

这张图表达了几个关键边界：

• 客户端不直接调用领域服务，而是通过网关和 BFF 进入系统；
• 订单、库存、支付各自拥有自己的数据库，其他服务不能随意跨库写入；
• 履约和通知通过消息队列消费事件，不应该被强行塞进下单同步链路；
• 订单链路里的同步依赖会影响用户实时体验，新增依赖必须受限；
• 异步消息承担削峰、解耦和补偿作用，不能因为局部修改被随意改成同步调用。

一份合格的 Architecture Map 至少要回答九个问题。

README 解决的是“这个仓库如何启动”，Architecture Map 解决的是“整个系统为什么这样组织，以及哪些边界不能破坏”。

三、领域模型：让 AI 知道哪些规则不能破坏

后端系统最重要的资产不是代码，而是业务不变量。

订单、支付、账户、会员、库存、风控、营销、履约、结算这些领域都有自己的实体、状态机、生命周期和约束。AI 如果只看代码，很容易写出“语法正确、业务错误”的实现。

例如订单系统常见的不变量包括：

• 已支付订单不能随意回到未支付；
• 退款金额不能超过支付金额；
• 库存扣减必须和订单状态保持一致；
• 优惠券不能重复核销；
• 账户余额不能变成负数；
• 同一请求不能重复入账；
• 风控拒绝后的交易不能绕过审批。

这些规则要写成可读、可测试、可断言的形式，而不是散落在代码分支里等待 AI 自己猜。

状态机要显式化

很多业务 bug 来自状态流转错误。订单状态、退款状态、审核状态、配送状态、账号状态，都应该有明确的状态枚举、允许路径、禁止路径、触发事件和补偿动作。

stateDiagram-v2
    [*] --> Created: 创建订单
    Created --> PendingPayment: 等待支付
    PendingPayment --> Paid: 支付成功
    PendingPayment --> Closed: 超时关闭
    Paid --> Fulfilled: 履约完成
    Paid --> Refunding: 发起退款
    Refunding --> Refunded: 退款成功
    Refunding --> Paid: 退款失败
    Closed --> [*]
    Fulfilled --> [*]
    Refunded --> [*]

状态机不仅要给人看，最好还能转成机器可读定义，用来生成校验逻辑和测试用例。

entity: Order
states:
  - Created
  - PendingPayment
  - Paid
  - Fulfilled
  - Refunding
  - Refunded
  - Closed

transitions:
  - from: Created
    to: PendingPayment
    event: ORDER_CONFIRMED
  - from: PendingPayment
    to: Paid
    event: PAYMENT_SUCCEEDED
  - from: PendingPayment
    to: Closed
    event: PAYMENT_TIMEOUT
  - from: Paid
    to: Refunding
    event: REFUND_REQUESTED

forbidden:
  - from: Paid
    to: Created
  - from: Closed
    to: Paid

invariants:
  - "refundAmount <= paidAmount"
  - "paid order must have exactly one successful payment record"
  - "closed order cannot be paid again"

这类定义可以直接变成 AI 的约束上下文。AI 在新增订单状态、修改退款逻辑、重构支付回调时，需要先通过状态机和不变量校验。

跨域链路模型要保护系统级一致性

单个服务内部正确，不代表整条业务链路正确。下单可能涉及用户、营销、订单、库存、支付、风控、履约和通知；退款可能涉及订单、支付、资金、库存、优惠券、结算和用户通知。局部修改一旦不了解跨域协作，就可能制造全局不一致。

sequenceDiagram
    participant U as 用户
    participant B as 订单 BFF
    participant R as 风控服务
    participant O as 订单服务
    participant I as 库存服务
    participant P as 支付服务
    participant M as 消息队列
    participant F as 履约服务

    U->>B: 提交订单
    B->>R: 风控校验
    R-->>B: 通过
    B->>O: 创建订单
    O->>I: 预占库存
    I-->>O: 预占成功
    O-->>B: 返回待支付订单
    U->>P: 支付
    P->>M: 发布 payment.succeeded
    M-->>O: 更新订单为已支付
    M-->>F: 触发履约

跨域链路模型要描述每一步是同步调用还是异步事件，失败后如何补偿，哪些步骤允许最终一致，哪些步骤必须强一致，哪些消息可以重复消费，哪些状态不能逆转，哪些异常需要人工介入。

领域模型回答“业务对象内部如何流转”，跨域链路模型回答“多个业务域之间如何协作”。前者保护实体不变量，后者保护系统级一致性。

四、把团队经验封装成 AI 可调用的 Skill

AI Coding 的效率不只取决于模型能力，还取决于模型外部的工具、上下文、流程和约束。团队应该把高频工程任务沉淀成 Skill。

Skill 可以理解为可复用任务包，包含任务说明、上下文入口、操作步骤、工具命令、校验方式、风险提示和输出格式。它不是普通文档，而是 AI Agent 执行任务时调用的操作手册。

常见后端 Skill 包括：

一个 Skill 可以这样写：

skill: add-database-field
appliesTo:
  - "需要给已有实体新增字段"
  - "字段需要兼容老版本读写"
notAppliesTo:
  - "需要拆表或迁移核心主键"
inputs:
  - serviceName
  - tableName
  - fieldName
  - fieldType
  - defaultValue
steps:
  - "检查 dataOwnership，确认当前服务拥有表写权限"
  - "新增 migration，字段必须允许默认兼容"
  - "更新 Entity、DTO、Mapper 和字段说明"
  - "先兼容写入，再兼容读取"
  - "补充单元测试和 Schema 检查"
  - "如果需要历史回填，生成独立回填脚本"
riskChecks:
  - "是否锁表"
  - "是否影响老版本客户端"
  - "是否涉及敏感字段"
  - "是否需要灰度开关"
validation:
  - "mvn test -pl ${serviceName}"
  - "mvn verify -Pschema-check"
output:
  - "变更点"
  - "兼容性说明"
  - "测试结果"
  - "回滚方案"

Skill 的价值是减少 AI 的猜测空间。资深工程师知道“加字段要先兼容写、再兼容读、再回填、再切流量、最后清理旧字段”，新人和 AI 未必知道。把这些经验沉淀成 Skill，本质上是在把组织经验变成可执行资产。

五、Harness：给 AI Agent 建立安全执行轨道

Skill 是能力包，Harness 是执行框架。它决定 AI 如何获得上下文、如何选择工具、如何执行命令、如何处理权限、如何验证结果、如何停止和上报。

后端无人值守开发不能让 AI 直接拥有无限权限。AI 必须运行在受控 Harness 中。

flowchart TD
    T[任务输入] --> C[上下文装载层]
    C --> P[计划层]
    P --> A{风险判断}
    A -->|低风险| E[执行层]
    A -->|高风险| H[人工审批]
    H --> E
    E --> V[验证层]
    V --> R{是否通过}
    R -->|通过| PR[创建 PR / 灰度方案]
    R -->|失败| F[停止并生成报告]
    PR --> O[审计与回滚记录]

一个面向后端的 Harness 至少需要七层能力。

Harness 的目标不是让 AI 更自由，而是让 AI 在正确轨道上更高效。越是大型后端系统，越不能依赖模型自觉，越要依赖工程化约束。

架构策略也要让 Harness 执行

Harness 不应该只是执行环境，还应该成为架构规则执行器。

架构师可以把服务分层、依赖方向、数据所有权、消息规范、核心链路约束、强依赖准入规则写成 Architecture Policy。AI 提交计划或修改代码时，Harness 自动检查是否违反边界。

典型检查包括：

• BFF 层是否直接写入核心业务库；
• 非 Owner 服务是否访问了其他服务私有表；
• 核心交易链路是否新增未登记的同步 RPC；
• 基础服务是否反向依赖业务服务；
• 原本异步解耦的链路是否被改成强同步调用；
• 消息 Schema 是否破坏兼容性。

过去这些问题依赖架构评审和 Code Review 发现，以后应该尽量通过策略和 CI 自动发现。

六、测试体系要成为 AI 的交通信号灯

AI Friendly 的后端系统里，测试不是“防人出错”的附属设施，而是约束 AI 行为的关键边界。测试不只回答“代码有没有错”，还要回答“AI 有没有资格继续往下走”。

架构级测试尤其重要。它不是验证某个函数返回值，而是验证系统结构没有被侵蚀。例如：

rules:
  - name: bff-cannot-write-domain-db
    match:
      layer: bff
      operation: write_database
    deny:
      databaseTags:
        - domain-owned

  - name: critical-path-no-new-sync-rpc
    match:
      path: createOrder
      dependencyType: sync-rpc
    requireApproval: architecture-owner

  - name: non-owner-cannot-access-private-table
    match:
      operation: read_or_write_table
    require:
      tableOwnerEqualsCurrentService: true

AI 每完成一个阶段，都应该经过对应 Checkpoint：

flowchart LR
    Plan[生成修改计划] --> Policy[架构策略检查]
    Policy --> Code[修改代码]
    Code --> Unit[单元测试]
    Unit --> Contract[契约测试]
    Contract --> Integration[集成测试]
    Integration --> Security[安全扫描]
    Security --> PR[创建 PR]

如果某个 Checkpoint 未通过，AI 应该停止并报告原因，而不是继续扩大修改范围。

七、可观测性要变成 AI 的眼睛

无人值守开发不只包括写代码，还包括排障、修复、优化和自愈。AI 要参与这些工作，必须能看见系统运行状态。

传统可观测性主要面向人：Dashboard 给人看，日志给人查，告警发到群里。AI Friendly 的可观测性要进一步结构化。

日志必须结构化

自然语言日志可以保留，但关键字段必须结构化。否则 AI 很难稳定检索和关联。

{
  "timestamp": "2026-06-07T10:00:00+08:00",
  "level": "ERROR",
  "service": "order-service",
  "traceId": "9f1c2a",
  "spanId": "3b8e",
  "bizId": "order_123",
  "userIdHash": "u_7d91",
  "errorCode": "INVENTORY_RESERVE_TIMEOUT",
  "latencyMs": 1200,
  "orderStatus": "PendingPayment",
  "dependency": "inventory-service"
}

错误码要有明确语义

不能所有异常都叫 SYSTEM_ERROR。AI 需要通过错误码判断问题类型：参数错误、依赖超时、库存不足、权限失败、幂等冲突、数据不一致，处理路径完全不同。

Trace 要能关联业务实体

AI 排查订单问题时，应该能从 orderId 找到完整调用链、消息链、数据库变更和状态流转，而不是只能看到某一次 HTTP 请求。

flowchart TD
    A[告警: 支付成功但订单未更新] --> B[读取 Runbook]
    B --> C[查询最近发布]
    C --> D[按 orderId 查询 Trace]
    D --> E[检查 payment.succeeded 消息]
    E --> F[检查 Consumer Lag]
    F --> G[定位失败原因]
    G --> H[生成修复或补偿方案]
    H --> I[执行测试并提交 PR]

告警必须关联 Runbook

没有 Runbook 的告警，对 AI 来说只是噪音。每个告警都应该关联：

• 可能原因；
• 排查步骤；
• 常用查询；
• 风险等级；
• 临时止血方式；
• 长期修复建议；
• 是否允许 AI 自动处理。

如果 AI 接到告警后可以读取上下文、查看最近发布、分析日志、查询 Trace、定位异常 Commit、生成修复 PR、跑测试并提交灰度方案，后端系统才接近无人值守工程闭环。

八、权限分级：AI Friendly 不能牺牲安全

AI Agent 可能需要读代码、查日志、跑测试、访问测试数据库、查询监控、读配置、操作分支和创建 PR。权限如果不分层，很容易制造事故。

合理的方式是建立分级权限模型。

AI Friendly 不是把权限全部交给 AI，而是在不同风险场景下给它刚好够用的权限。

数据安全也要单独设计：

• 日志中的手机号、身份证、邮箱、地址、支付信息、Token、Cookie、密钥必须脱敏；
• AI 不应该直接接触明文敏感数据；
• 生产数据库查询默认只读，并限制行数、字段和时间窗口；
• 所有生产查询都要审计；
• 密钥、证书、生产配置必须通过 Secret Manager 管理，不能进入 Prompt、日志或代码生成上下文。

能力越强的 AI，越需要严格边界。能力弱的 AI 最多写错代码，能力强但权限失控的 AI 可能直接造成生产事故。

九、代码结构要可导航，让 AI 少猜路径

AI 修改代码的效率，很大程度取决于代码库是否可导航。一个 AI Friendly 的后端仓库，应该有稳定的目录约定、命名约定和分层约定。

典型结构可以这样组织：

order-service/
  src/main/java/
    controller/
    application/
    domain/
      model/
      service/
      state/
      event/
    infrastructure/
      repository/
      client/
      messaging/
      cache/
    config/
  src/test/
  docs/
    service-card.yaml
    domain-model.yaml
    runbook/

几个原则非常重要：

• controller 只负责协议适配，不承载核心业务规则；
• application 编排用例流程，不直接写复杂领域逻辑；
• domain 放实体、状态机、不变量和领域服务；
• infrastructure 封装数据库、缓存、消息和外部服务；
• 外部依赖必须通过 client 封装，不能散落在业务代码里；
• 每个消息 Topic 有明确 Producer 和 Consumer；
• 每个配置项有说明、默认值和作用域；
• 每张表有对应 Repository，避免 SQL 到处散落。

还要减少隐式魔法。复杂反射、动态代理、运行时拼接、隐式扫描、约定大于配置并不是不能用，但必须可解释、可追踪、可测试。AI 越容易找到正确入口，越不容易在错误层级乱改。

十、Docs as Code 与 Architecture as Code

文档如果不进入工程流程，迟早会腐化。AI Friendly 的文档应该遵循 Docs as Code：文档放在仓库里，和代码一起 Review、一起版本管理、一起参与 CI 检查。

常见约束包括：

CI 可以自动检查：新增 Controller 但没有更新接口文档，新增 Migration 但没有字段说明，新增 Consumer 但没有 Topic 文档，都应该阻止合并。

大型后端系统还需要 Architecture as Code。也就是把架构分层、服务归属、依赖方向、数据所有权、消息契约、核心链路、风险等级、发布边界等信息，用结构化文件维护，并让它们参与 CI/CD（Continuous Integration / Continuous Delivery，持续集成与持续交付）。

可以用这些文件承载规则：

• architecture.yaml：业务域、服务分层、允许依赖方向；
• ownership.yaml：每张表、每个 Topic、每个 API 的 Owner；
• critical-path.yaml：核心链路、延迟预算、强依赖准入规则；
• risk-policy.yaml：不同风险等级下 AI 能自动执行到哪一步；
• release-policy.yaml：灰度、发布、回滚和审批规则。

这样，架构就不再只是 Wiki 或 PPT，而是 AI 能读取、CI 能校验、Harness 能执行的工程资产。

十一、从 Copilot 到 Coworker，再到 Operator

后端系统 AI Friendly 的建设，可以分成三个阶段。

所谓无人值守开发，不是一步到位让 AI 接管生产，而是逐步扩大 AI 的可信半径。先让它在低风险、强验证的区域自动化，再逐步进入复杂系统和生产运维。

flowchart LR
    A[Copilot<br/>辅助编码] --> B[Coworker<br/>独立 PR]
    B --> C[Operator<br/>参与值守]
    A --> A1[代码规范<br/>测试入口]
    B --> B1[Service Card<br/>Skill<br/>领域模型]
    C --> C1[可观测性<br/>权限分级<br/>审计回滚]

十二、一条可落地的改造路线

团队不需要一开始就搭建宏大的 AI 平台。更现实的做法是选择一个中等复杂度、风险可控的业务域做试点，先把系统事实和验证机制补起来。

这条路线的关键不是追求“无人化”，而是追求“可验证”。只有每一步都能验证，自动化才有扩大范围的基础。

十三、AI Friendly 最终改变的是软件组织方式

AI Friendly 后端架构不是为了迎合 AI，而是为了让系统知识更清晰、工程流程更规范、风险控制更自动化。

一个真正适合 AI Agent 参与工程活动的后端系统，应该具备这些特征：

• AI 能快速知道每个服务负责什么；
• AI 能理解核心实体、状态机和业务不变量；
• AI 能找到正确代码位置，而不是全局乱搜；
• AI 能按照团队沉淀的 Skill 完成任务；
• AI 能在受控 Harness 中修改、测试、提交；
• AI 能通过自动化测试验证自己的改动；
• AI 能读取脱敏后的运行态信息进行排障；
• AI 的每一步操作都有权限边界和审计记录；
• AI 生成的变更包含影响面分析、测试结果和回滚方案；
• AI 在低风险场景中可以自动推进，在高风险场景中知道停止并请求人工决策。

即使暂时不引入 AI，这些改造也能提升团队效率：架构边界更清楚，文档更可信，测试更完整，排障更快，发布更安全。一旦 AI Agent 能力成熟，这些工程资产会决定团队能否把 AI Coding 从“代码生成工具”升级成真正的工程生产力系统。

未来的后端架构师不只要设计高并发、高可用、高扩展的系统，还要设计可被 AI 理解、可被 AI 修改、可被 AI 验证、可被 AI 运维的系统。