三层 API

xly 不是只有一个 API，而是有三层，分别由三个独立的 Spring Boot 服务承载，面向不同受众，也有不同的运行契约。任何集成讨论的第一步，都是先确认你在和哪一层对话。

层级	服务	Context path	受众
内部	xlyEntry	/xlyEntry	xly SPA 自身（BACK + FROUNT）。对外部调用方不是稳定契约。
外部	xlyApi	/xlyApi	从外部调用 xly 的租户和集成方。数据驱动的公开 API。
入站 webhook	xlyInterface	/xlyInterface	将事件推送进 xly 的第三方系统。带 Swagger。

每个服务都会构建成自己的 WAR，并在自己的 JVM 中运行。它们不共享进程内状态；它们共享的是数据库。正是这个共享数据库让服务拆分成立：内部 API 写入的数据会自动被外部 API 读到，因为两者都连接同一个 schema。

为什么是三层，而不是一层

每一层回答的问题不同，合在一起会牺牲清晰度：

• 内部层很大（对所有元数据驱动模块做通用 CRUD）、易变（随框架变化）、且有意保持弱类型（SPA 决定要什么，服务端照元数据执行）。
• 外部层是收敛后的接口（只暴露允许集成方使用的端点），按 sApiCode 做版本化，并用 bearer token 认证。它能跨框架变化保持稳定，正是因为它小而明确。
• 入站 webhook 层接收来自第三方系统的不可信 body，并路由到 xly 处理器。Swagger UI 放在这里，因为这个受众最需要交互式文档。

每一层在运行时长什么样

• 内部层 — 见四表读取。一个端点（/business/getModelBysId）返回完整表单布局；另一个端点（/business/addUpdateDelBusinessData）写入元数据命名的任意表中的任意行。端点少，形状通用。
• 外部层 — 大多数调用走 /api/invoke/{sApiCode}。sApiCode 是 sysapi 元数据表中的一行，定义 SQL 模板、参数、认证要求和目标。新的外部 API 是注册成数据，不是写成代码；这和框架对自身表单采用的数据驱动基本论点一致。
• 入站 webhook 层 — /interfaceDefine/invoke/{interfaceInvoke} 接收载荷，查找元数据中的匹配处理器，运行配置好的 SQL 或存储过程。此外还有少量为特定伙伴准备的硬编码接收器（/Push、/Pull、/send/sendQw）。

下一步看哪里

• API 参考（内部） — SPA 使用的 xlyEntry 端点；不面向外部调用方。
• API 参考（外部） — 集成方使用的 xlyApi 接口面，以及 sysapi 驱动的 /api/invoke 模式。
• API 参考（Webhook） — xlyInterface 入站接口面，以及 Swagger UI 的服务地址。
• API 参考（消息） — 补充 HTTP API 的 ActiveMQ / RocketMQ 事件通道。