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 require hongxunpan/simple-api
php bin/simple module:enable api

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

普通响应

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

{
    "code": 0,
    "msg": "success",
    "data": {
        "id": 1,
        "name": "示例"
    }
}

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 错误协议。

项目响应覆盖

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

use HongXunPan\SimpleApi\Response\StandardResponseContent;

final class ProjectResponseContent extends StandardResponseContent
{
    public function toArray(): array
    {
        return parent::toArray() + [
            'info' => [
                'version' => config('app.version'),
            ],
        ];
    }
}

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

use HongXunPan\SimpleApi\Response\ResponseContentContract;
use HongXunPan\SimpleApi\Response\StandardJsonResponse;

final class ProjectResponse extends StandardJsonResponse
{
    protected function createContent(mixed $content): ResponseContentContract
    {
        return new ProjectResponseContent($content);
    }
}

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

项目异常映射

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

use HongXunPan\SimpleApi\Exception\ExceptionMapper;
use HongXunPan\SimpleApi\Exception\ExceptionResponse;
use HongXunPan\SimpleApi\Response\StandardResponseContent;
use Throwable;

final class ProjectExceptionMapper implements ExceptionMapper
{
    public function map(Throwable $throwable): ?ExceptionResponse
    {
        if ($throwable instanceof ProjectApiException) {
            return new ExceptionResponse(
                status: 200,
                body: new StandardResponseContent(
                    data: $throwable->getData(),
                    code: $throwable->getCode(),
                    message: $throwable->getMessage(),
                ),
            );
        }

        return new ExceptionResponse(
            status: 200,
            body: new StandardResponseContent(
                data: [],
                code: -1,
                message: 'Server Error',
            ),
        );
    }
}

项目 Provider 登记 Mapper：

use HongXunPan\SimpleApi\Exception\ExceptionMapperRegistry;

$app->make(ExceptionMapperRegistry::class)->append(
    $app->make(ProjectExceptionMapper::class),
);

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

验证

composer test

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