# 5. API 参考

xly 暴露了三个不同的 HTTP 接口面，分别由三个独立的 Spring Boot 服务承载。每个接口面都在下面的独立页面中说明；概念总览见[概念 / 三层 API](../concepts/api-surface.md)。

| 页面 | 服务 | Context path | 适用场景 |
|---|---|---|---|
| [内部 API](internal.md) | `xlyEntry` | `/xlyEntry` | 你在扩展 SPA，或维护框架运行时。 |
| [外部 API](external.md) | `xlyApi` | `/xlyApi` | 你在接入会从外部调用 xly 的系统。 |
| [Webhook](webhooks.md) | `xlyInterface` | `/xlyInterface` | 第三方系统需要把事件推送进 xly。 |
| [消息](messaging.md) | `xlyEntry` + `xlyErpJms*` | 不适用（ActiveMQ / RocketMQ） | 异步、扇出式集成比同步 HTTP 调用更合适。 |
| [通知](notifications.md) | `xlyMsg`（作为库被 `xlyEntry`、`xlyBusinessService`、`xlyInterface` 使用） | 不适用（钉钉 / 微信 API） | 业务事件需要向用户推送聊天平台消息。 |

## 阅读顺序

如果你是外部集成方，从[外部 API](external.md) 开始。如果你是扩展框架的 Java 开发者，从[内部 API](internal.md) 开始（通用 CRUD 机制的大部分内容在[维护人员运行时章节](../reference/maintainer/runtime.md)中说明；本章会交叉链接到那里）。

## 跨接口面的共同事实

- **认证。** 内部调用使用 SPA 的 session cookie + `@CurrentUser` 参数解析器。外部调用使用从 `/xlyApi/token/getToken` 获取的 bearer token。Webhook 按通道约定认证方式（签名 header、查询参数密钥等）。
- **租户作用域。** 每个服务中，所有已认证控制器方法在做任何工作前都会执行 `RequestAddParamUtil.me().addParams(params, userInfo)`；见[多租户概念页](../concepts/multi-tenancy.md)。绕过这一步的请求就是多租户 bug。
- **日志。** 外部调用写入 `sysapilog`；内部调用使用框架标准的 `syslog4j` 配置；Webhook 由各通道处理器自行决定日志方式。