REST API 设计中最让人头疼的往往不是业务逻辑，而是路由表随着资源数量增长变得越来越复杂。比如用户下面的文章、文章下面的评论，如果每个层级都去写独立的正则匹配，代码很快就会失去可读性。Bullet PHP 框架把每一个 URL 段当作一个资源节点来对待，资源之间可以像树一样嵌套，HTTP 方法则用来表达对资源的操作。这种组织方式和 REST 的理念天然契合，下面通过具体步骤来看如何落地。

安装与基本应用结构

Bullet 框架通过 Composer 安装，最基础的方式是从 Packagist 拉取依赖。在项目根目录执行 composer require 命令即可，命令执行完成后会自动生成 vendor 目录以及 autoload 文件。这个框架本身非常轻量，不依赖其他大型组件，核心就是一个启动器和请求对象。

安装完成后，创建一个入口文件，比如 index.php。在文件中引入自动加载文件，然后实例化 Bullet\App 类。App 对象是整个应用的入口，它负责接收请求、匹配资源树并执行对应的回调函数。最后调用 run 方法并传入一个 Bullet\Request 对象，框架就会根据当前请求的 URL 和 HTTP 方法找到对应的处理逻辑。

composer require vlucas/bulletphp

<?php
require 'vendor/autoload.php';
$app = new Bullet\App();
$app->path('/', function($request) {
    return 'Hello Bullet';
});
echo $app->run(new Bullet\Request());

上面的代码演示了最简可运行结构。path 方法用于绑定根路径，回调函数接收请求对象作为参数，返回的字符串会被直接输出。实际开发中通常不会直接输出字符串，而是返回数组或者更复杂的响应体，但这已经能说明 Bullet 的路由核心机制：先用 path 或 resource 定义资源节点，再用回调处理逻辑。

有一点需要特别注意，Bullet 的请求对象不是 PHP 原生的全局变量，而是框架封装的 Bullet\Request 对象。这个对象提供了很多便捷方法来读取请求头、请求体以及 URL 中的分段参数，在后续的资源回调里会频繁用到。

定义用户资源并通过 HTTP 方法分发

REST API 中用户是最常见的资源，比如 /users 表示用户集合，/users/123 表示单个用户。Bullet 使用 resource 方法来定义一个资源节点，这个方法会自动处理集合与单个资源的关系，不需要手动写两套路由。回调函数内部可以通过请求对象的 getID 方法获取 URL 中对应的 ID 部分，如果访问的是 /users，则 getID 返回空值，如果访问的是 /users/123，则返回字符串 123。

HTTP 方法的分发也是在这个回调里完成的。Bullet 的请求对象提供了 isGet、isPost、isPut、isDelete 等方法，用来判断当前请求使用了哪种 HTTP 动作。在回调内部根据不同的方法返回不同的数据，就能实现一个标准的资源控制器。下面是一个完整的用户资源示例，展示了如何区分列表、详情、创建、更新和删除操作。

$app->resource('users', function($request) {
    $id = $request->getID();
    if ($request->isGet()) {
        if ($id) {
            return ['id' => $id, 'name' => 'Alice'];
        }
        return [
            ['id' => 1, 'name' => 'Alice'],
            ['id' => 2, 'name' => 'Bob']
        ];
    }
    if ($request->isPost()) {
        $data = $request->post();
        return ['created' => true, 'data' => $data];
    }
    if ($request->isPut()) {
        $data = $request->put();
        return ['updated' => true, 'id' => $id, 'data' => $data];
    }
    if ($request->isDelete()) {
        return ['deleted' => true, 'id' => $id];
    }
    return ['error' => 'Method not allowed'];
});

从代码里可以看出，所有逻辑都集中在一个资源回调中，这种做法和传统 MVC 控制器中的多个方法有些不同。它的好处是资源相关的处理都在同一个地方，调整业务逻辑时不需要在多个方法之间跳转。代价则是回调函数可能会变长，因此实际项目中通常会把数据库操作封装到模型或服务类里，回调只负责调用并返回结果。

请求参数方面，post 和 put 方法分别用于读取 POST 和 PUT 请求体中的数据。Bullet 会自动解析 JSON 请求体为数组，如果请求体是表单格式，也会自动转换成关联数组。这意味着客户端无论是发送 JSON 还是表单，服务端代码都不需要关心底层解析细节，框架已经完成了这一步。

嵌套资源处理一对多关系

用户和文章是一对多关系，对应的 URL 通常是 /users/123/posts 和 /users/123/posts/456。在 Bullet 中实现嵌套资源并不需要重新定义外层路径，而是直接在用户资源回调内部继续调用 path 方法。这样路径中的 users 和 posts 就形成了父子关系，子资源可以访问到父资源的 ID，从而实现数据隔离。

下面这段代码展示了如何在用户资源下挂载文章子资源。注意子资源的回调函数中调用了 getID 方法，这个方法在子资源内部返回的是 /posts 后面的 ID，而不是用户 ID。用户 ID 来自外层变量，通过 use 语句捕获到闭包作用域中。

$app->resource('users', function($request) {
    $user_id = $request->getID();
    if ($request->isGet() && $user_id) {
        $request->path('posts', function($request) use ($user_id) {
            $post_id = $request->getID();
            if ($request->isGet()) {
                if ($post_id) {
                    return ['post_id' => $post_id, 'user_id' => $user_id, 'title' => 'Post title'];
                }
                return [
                    ['post_id' => 101, 'user_id' => $user_id, 'title' => 'First post'],
                    ['post_id' => 102, 'user_id' => $user_id, 'title' => 'Second post']
                ];
            }
            if ($request->isPost()) {
                $data = $request->post();
                return ['created' => true, 'user_id' => $user_id, 'data' => $data];
            }
        });
    }
});

这种嵌套写法的核心优势在于结构清晰。当你看到代码时，可以直观地知道哪些资源属于哪个父资源。如果 URL 是 /users/999/posts/888，程序会先进入 users 资源回调，捕获到 user_id 为 999，然后进入 posts 子资源回调，post_id 为 888。整个过程不需要正则表达式，也不需要在全局路由表中维护顺序，完全按照 URL 的层级逐层匹配。

嵌套层级理论上可以继续向下延伸，比如文章下面的评论，只需要在 posts 回调内部再调用 path 方法即可。但要注意，层级过深会让闭包嵌套变多，代码缩进过重，这时可以考虑把子资源的回调提取成独立的函数，然后通过 use 传入必要的父级参数。

返回数组、内容协商与响应头设置

Bullet 框架一个很实用的特性是自动内容协商。当回调函数返回一个数组时，框架会根据请求头中的 Accept 字段来决定最终输出 JSON、XML 还是 HTML。默认情况下，如果客户端发送 Accept: application/json，返回数组会被序列化成 JSON 字符串；如果 Accept 是 text/html，框架会尝试把数组渲染成一个简单的 HTML 页面。

如果不想依赖客户端发送的 Accept 头，也可以在回调内部直接返回一个响应对象，明确指定内容类型和状态码。下面这个例子展示了如何返回一个带状态码和自定义响应头的 JSON 响应。对于需要精确控制输出格式的接口来说，这种方式更加可靠。

$app->resource('status', function($request) {
    if ($request->isGet()) {
        $response = new Bullet\Response();
        $response->status(201);
        $response->header('Content-Type', 'application/json');
        $response->body(json_encode(['status' => 'ok']));
        return $response;
    }
});

使用响应对象的好处是可以完全掌控返回的头信息。比如可以设置 Cache-Control 头来控制缓存，也可以设置 Location 头来配合 201 Created 状态码。不过大多数简单场景下直接返回数组会更方便，Bullet 会自动处理序列化和默认头信息。

除了返回数组和响应对象，回调还可以返回字符串、布尔值或者 null。返回字符串会被当作 HTML 文本输出，返回布尔值 true 或 false 会被转换成对应的文本。这些行为虽然简单，但在开发调试接口时非常有用，可以快速验证路由是否命中。

错误处理与调试技巧

接口开发中错误处理往往容易被忽略，但它直接影响前端调用体验。Bullet 框架支持异常捕获机制，可以在应用级别注册一个异常处理器，统一返回 JSON 格式的错误信息。这样做的好处是所有错误都从一个出口输出，前端只需要处理一种错误结构，不需要针对不同异常分别判断。

下面是一个基本的错误处理示例。通过 App 对象的 on 方法注册异常事件，当框架内部抛出异常时会触发这个回调。在回调中根据异常类型决定状态码，然后返回一个统一格式的错误数组。

$app->on('Exception', function($e) {
    $status = 500;
    if ($e instanceof Bullet\Exception\NotFound) {
        $status = 404;
    }
    $response = new Bullet\Response();
    $response->status($status);
    $response->header('Content-Type', 'application/json');
    $response->body(json_encode([
        'error' => $e->getMessage(),
        'code' => $status
    ]));
    return $response;
});

如果访问了一个未定义的资源，比如 /users/abc 下的未知子路径，框架会抛出 NotFound 异常，异常处理器会捕获它并返回 404 状态码。这样前端就能得到一致的错误提示，而不是一个 PHP 默认的堆栈输出。对于生产环境来说，这种统一错误处理非常重要。

调试方面，可以在开发环境中开启 Bullet 的调试模式，让框架输出详细的错误信息。另外，在回调函数中可以使用 error_log 函数或者直接 var_dump 请求对象的关键属性，帮助理解请求是如何被解析的。虽然 Bullet 没有自带复杂的调试工具，但它的简单结构让排查问题变得相对直观，只需要关注资源树和回调函数即可。