Scramble项目中状态码与返回类型注解的配合使用

在PHP API文档生成工具Scramble中，开发者经常会遇到需要同时指定响应状态码和返回类型的情况。本文深入探讨如何正确处理这两种注解的配合使用。

状态码注解与返回类型的关系

Scramble的@status注解用于指定API端点返回的HTTP状态码，而@return或@body注解则用于定义响应体的数据结构。这两种注解在功能上是互补的，但在实际使用中存在一些需要注意的配合规则。

常见问题场景

当开发者尝试在返回分页资源集合时同时指定状态码，可能会遇到@status注解失效的情况。例如：

/**
 * @return AnonymousResourceCollection<LengthAwarePaginator<TestResource>>
 */
public function bulkStore(TestRequest $request)
{
    /**
     * @status 201
     */
    return (TestResource::collection($this->createTests($request)))->toResponse()->setStatusCode(201);
}

这种情况下，@status 201的指定不会生效，因为Scramble的设计机制要求状态码注解必须与@body注解配合使用，或者完全不使用任何注解。

正确的使用方式

方法一：配合@body注解使用

public function bulkStore(TestRequest $request)
{
    /**
     * @status 201
     * @body AnonymousResourceCollection<LengthAwarePaginator<TestResource>>
     */
    return (TestResource::collection($this->createTests($request)))->toResponse()->setStatusCode(201);
}

这种方式明确指定了响应状态码和响应体结构，是最规范的写法。

方法二：依赖自动推断（Scramble 0.11.1+）

public function bulkStore(TestRequest $request)
{
    return (TestResource::collection($this->createTests($request)))->toResponse()->setStatusCode(201);
}

在新版本中，Scramble能够自动从响应对象中推断出状态码和返回类型，大大简化了注解的编写。

设计原理分析

Scramble之所以这样设计，是为了保持注解语义的清晰性。@return注解传统上仅用于描述方法的返回值类型，而不包含HTTP层面的信息。将状态码与响应体结构分开定义，可以使文档生成更加模块化和可维护。

最佳实践建议

1. 对于简单的API端点，可以依赖Scramble的自动推断功能
2. 对于复杂的响应结构，建议同时使用@status和@body注解
3. 避免混用@return和@status注解，这会导致不可预期的行为
4. 保持注解的简洁性，只在必要时添加显式注解

通过理解这些规则，开发者可以更高效地使用Scramble生成准确、规范的API文档。