Download the PHP package hongxunpan/simple-api without Composer

simple-api

hongxunpan/simple-api 为 hongxunpan/simple-framework 提供可按需安装、显式启用的 JSON Response 与 JSON 异常渲染机制。

本包负责：

• JSON 编码、HTTP 状态与响应头发送；
• 基于 Arrayable 的响应内容契约与默认 code / msg / data 结构；
• 异常 Mapper 契约、Registry 与 JSON Renderer；
• 将 framework 的 ResponseContract 与 ExceptionRenderer 切换到 JSON 实现。

本包不提供任何默认异常映射，也不负责业务错误码、路由错误策略、鉴权、Token、RBAC、 SQL 调试、日志 Channel、第三方异常上报或 Eloquent 序列化。默认响应结构可由项目继承 扩展或完全替换；底层 JsonResponse 仍支持任何 json_encode 可编码的内容。

安装与启用

Composer 安装与 Module 启用是两个独立动作。API Module 首版没有 helper、项目配置文件、 发布资源或 Installer。

普通响应

启用后，普通路由返回值由 StandardJsonResponse 包装并编码：

StandardResponseContent 通过 ResponseContentContract 继承 Illuminate Arrayable， 负责把响应内容转换为通用数组；StandardJsonResponse 只负责使用该内容并发送 JSON。 项目如果不需要默认结构，可将 ResponseContract 直接绑定到纯 JsonResponse。

完整异常仍由 framework 的 ExceptionReporter 处理。simple-api 不绑定 Reporter， 也不读取日志配置。

异常策略边界

simple-api 不识别 RouteException、业务异常或第三方异常，也不决定 HTTP 200、404、405 或 500。Module 启用后 Registry 默认为空，项目应至少登记一个能够处理全部 Throwable 的兜底 Mapper，才能保证所有异常都返回项目约定的 JSON。

如果没有 Mapper 命中，JsonExceptionRenderer 会明确失败，framework ErrorHandler 随后回退到安全纯文本 Renderer。这个回退只保证不泄漏原始异常，不代替项目定义 JSON 错误协议。

项目响应覆盖

项目可以继承默认内容实现，增加稳定的项目字段：

项目 Response 负责选用该内容实现以及扩展 Header：

再由项目 Provider 将 framework 的 ResponseContract 绑定到 ProjectResponse。 项目 Provider 应登记在 config('module.provider-override')，其注册顺序晚于 Module Provider。 如果调用方已经返回任意 ResponseContentContract 实现，StandardJsonResponse 会直接使用， 不会再次包装。

项目异常映射

项目异常不需要继承 simple-api 的异常基类。项目实现 ExceptionMapper，自行决定异常分类、 HTTP 状态、响应结构和安全文案：

项目 Provider 登记 Mapper：

多个 Mapper 按顺序匹配，第一个非空结果生效。项目可将具体异常 Mapper 放在前面，并将 兜底 Mapper 放在最后。Mapper 或 JSON Renderer 自身失败时，framework ErrorHandler 会继续回退到安全纯文本 Renderer。

验证

测试覆盖 Module 元数据、Arrayable 内容契约、默认响应结构、纯 JSON 编码、Header 与状态 校验、项目内容扩展、Mapper 优先级与未命中行为、Provider 覆盖顺序以及项目最终 Response 绑定。