AI 概念图｜请求通过受控网关进入业务编排，非产品实机截图。

✦ 01｜为什么 AI 写出 API，企业仍需要接口引擎

一笔采购审批看起来只是“把状态改成通过”。真实流程还要核对审批人、当前状态、金额范围、库存或预算、重复请求、通知、操作日志和调用方身份。AI 一次性写出的 Controller 也许能跑通 happy path，却未必自动继承整个系统的租户与权限边界。

吾码接口引擎把业务 API 定义保存在 `sys_apiengine`，由 `ApiEngineKey` 定位，由 V8 JavaScript 组织业务。它不是让 AI 放弃编码，而是给代码一个已有的租户、路由、运行时与服务能力环境。单表 CRUD 优先用表单引擎；超出标准 CRUD 的规则和编排再写接口引擎。

结构解释图（确定性渲染）｜请求、鉴权、V8 逻辑、事务与响应各有边界。

✦ 02｜一个接口由代码和配置共同决定

接口配置不仅有 `ApiEngineKey`。`ApiAddress` 可定义自有地址，`ApiRoutes` 允许登记多个历史兼容地址；

`RequestType` 限制 GET/POST，`ParamType` 描述 form/json/url 输入，V8 内统一通过 `V8.Param` 读取。`IsAnonymous` 控制匿名调用，`StopHttp` 把内部接口挡在外部 HTTP 之外。

`IsResponseFile` 与 `ResponseType` 控制 JSON、字符串、HTML、文件、流或受控原始 HTTP 响应；

`LockKey/Timeout/LockMsg` 用于分布式互斥，`RateLimit` 用于频率限制，`LogParam/LogResult` 用于审计。启用、代码、路由、匿名、限流都要作为同一份配置回读，不可只更新代码却丢掉原配置。

• 默认内部业务接口不开放匿名；第三方回调确需匿名时，在脚本内仍要做验签、重放保护和业务授权。
• `StopHttp=true` 适合只允许其它接口或表单事件内部调用的逻辑。
• 自定义路由与多路由须避免冲突；兼容旧地址时同时核对 HTTP 方法、请求格式和返回契约。
• 日志不能无差别记录密码、Token、密钥或完整敏感返回值。

结构解释图（确定性渲染）｜路由、身份、响应、并发和审计共同定义 API。

✦ 03｜最小业务接口：让事务和错误码说真话

接口代码可以直接返回 DosResult。当前事务契约是：`Code:1` 成功提交；非 1 回滚。不要在接口引擎里手动 `Commit/Rollback`。后端读取当前 `V8.CurrentUser` 与 `V8.OsClient`，不能信任请求 JSON 伪造的用户或租户字段。

var id = String(V8.Param.Id || '').trim();
if (!id) return { Code: 0, Msg: '缺少单据 Id' };
var row = V8.FormEngine.GetFormData('diy_purchase', { Id: id });
if (row.Code !== 1) return { Code: 0, Msg: '单据不存在' };
if (row.Data.Status !== 'Pending') return { Code: 0, Msg: '当前状态不可审批' };
// 这里还须按权威角色、部门、金额和审批链校验当前用户。
var saved = V8.FormEngine.UptFormData('diy_purchase', { Id: id, Status: 'Approved' });
if (saved.Code !== 1) return saved;
return { Code: 1, Data: { Id: id, Status: 'Approved' } };

这是最小结构示意，不能直接用作生产审批：真正写入要用条件更新或状态机防并发，服务端重算审批资格与金额，使用稳定请求 Id 幂等，并处理通知失败与重试。成功码不是对业务事实的猜测，必须来自真实写入结果。

✦ 04｜V8 不是孤立脚本：后端能力按职责组合

接口引擎可调用 `V8.FormEngine` 做受控 CRUD 和分页筛选；复杂数据库查询用参数化 `V8.Db/DbRead`；缓存用 `V8.Cache`；外部系统用 `V8.Http`；内部复用用 `V8.ApiEngine.Run`。文件、Office、MQ、MongoDB、翻译、图像、AI 等能力也可在对应租户与权限条件下接入。

普通单表查询先用 `_Where`，需要 SQL 时动态值必须通过 `AddInParameter` 绑定。`V8.Http` 调第三方应指定超时并检查状态；第三方密钥若不能暴露给可编辑 V8，就把密钥操作压到最小可信后端原子。接口引擎继续负责路由、日志、数据写入和业务编排。

var rows = V8.FormEngine.GetTableData('diy_purchase', {
  _Where: [['Status', '=', 'Pending']],
  _SelectFields: ['Id', 'OrderNo', 'Amount'],
  _PageIndex: 1, _PageSize: 20
});
if (rows.Code !== 1) return rows;
return { Code: 1, Data: rows.Data, DataCount: rows.DataCount };

可复用能力不等于允许任意 SQL、任意外部地址或跨租户读写。AI 必须先读当前 Schema、权限和接口配置，再决定使用哪种 V8 能力；不要把请求参数直接拼进 SQL、表名、HTTP 目标或文件路径。

✦ 05｜响应不只有 JSON：文件、HTTP、流与实时事件

接口可返回标准 JSON、字符串、HTML 或文件。文件响应要开启 `IsResponseFile`，返回文件名、真实 `ContentType` 和 Base64 字节；浏览器预览器可能先发 `HEAD`，动态下载路由也应验收 HEAD 可达。

需要 302 跳转、特定状态码、XML 或白名单响应头时，可配置 `ResponseType=HTTP` 并返回 `DataAppend.HttpResponse`。`Location` 等头受宿主校验，普通 V8 不能随意设置 `Set-Cookie` 或伪造安全 Header。

return {
  Code: 1,
  DataAppend: { HttpResponse: {
    StatusCode: 302, Body: '',
    ContentType: 'text/plain; charset=utf-8',
    Headers: { Location: '/sso/continue', 'Cache-Control': 'no-store' }
  } }
};

大模型逐步反馈等场景可用 `ResponseType=Stream` 输出 SSE 或 NDJSON，但流中分片属于暂态，只有事务提交后的 done 才代表完成。

跨客户端实时刷新可在成功返回中声明 `DataAppend.RealtimeEvent`，由提交后的通用 SignalR Hub 广播；客户端仍须用 HTTP 快照补齐断线、乱序或丢失事件。

结构解释图（确定性渲染）｜JSON、文件、流与实时事件各有适用范围。

✦ 06｜锁、限流与幂等：三个问题别混成一个

`RateLimit` 限制单位时间的入口频率；`LockKey` 用共享 Redis 锁减少多个节点并发执行；业务幂等用稳定请求键、唯一约束、条件更新或状态机避免重复副作用。它们解决的问题不同，拿到锁也不等于业务只执行一次。

`LockKey` 填请求参数字段名，平台自动按租户隔离。普通调用的锁租期不会自动延长；可信持久后台任务才有受控续租。扣款、库存、积分、导入、对账必须额外有数据库层的冲突约束和恢复策略。

✦ 07｜长任务、异步调用与系统集成

当前请求必须等到结果的 I/O，可以调用 `V8.Http.*Async`、`V8.FormEngine.*Async` 或 `V8.ApiEngine.RunAsync` 并 `await`。

需要“先响应、稍后可靠处理”时，应使用接口引擎后台任务、Job、MQ 或 outbox，而不是在接口里 `setTimeout` 后提前返回。请求结束后运行时与事务会释放，计时器不能承担可靠业务。

预计超过 2 分钟、处理 500 条、1000 个扇出子操作或 100 次外部调用时，优先改为真实后台任务；超过 10 分钟还要用 `HasMore + Checkpoint` 分片，记录真实 Current/Total 与恢复点。流式响应负责在线增量显示，不能替代持久任务。

跨系统 HTTP、MQ、MQTT、定时任务和 OCR/AI 都可能把结果回送接口引擎。入口负责鉴权与业务幂等，后台消费负责重试和去重，数据库负责最终状态；这些边界比“AI 一次写出多少行代码”更重要。

✦ 08｜如何让 AI 在接口引擎里写对代码

请先读取当前租户的表结构、接口引擎、角色权限和相关 V8 Skill。
为采购审批设计接口引擎：给出 ApiEngineKey、请求方法、路由、匿名/StopHttp、
限流/锁/日志配置，服务端重新验证审批资格与状态。
先输出读写表、事务与幂等方案，再生成 V8 代码；只执行 dry-run。
列出成功、重复提交、无权限、旧状态、上游超时、并发与租户隔离测试。

在 Microi吾码AI 工作流里，AI 应先 `microi_list_engines` 找现有 Key、`microi_get_engine_code` 读当前版本，确认后再 `microi_save_engine_code`，并保留 HTTP 元数据；

只有目标不存在才创建。调用 `microi_run_engine` 可做最小调试，但最终还要走真实 HTTP 请求测试路由、Body、Header 和返回。

开发顺序应是：标准表单 CRUD 能解决就先复用；复杂规则用接口引擎；确实缺少平台可复用的底层原子能力才扩展可信 C#。需要应用交付时，将接口作为应用包资源声明策略，发布后按目标租户版本安装与回读。

✦ 09｜验收清单：从“能跑”到“可交付”

• 用授权账号、无权限账号、匿名请求分别验证身份；请求内伪造 `_CurrentUser` 或租户字段不能改变真实身份。
• 验证稳定 `/apiengine/{ApiEngineKey}`、自定义地址、兼容地址在冷缓存首次请求和节点重启后仍正确。
• 验证 `Code:1` 提交与错误回滚、幂等键、并发冲突、锁失效、限流和日志脱敏。
• 文件核对字节与 ContentType，流核对提交后 done，实时事件核对重连补快照。
• 后台任务核对真实进度、checkpoint、重复消费和故障恢复；不能只凭一次 HTTP 200 宣称完成。

文中 AI 概念图与图文卡底图由 AI 生成；结构示意图依据当前源码与配置确定性绘制。概念图不是产品实机截图，功能以项目版本、配置和权限为准。