php-api

PHP API 开发技能

掌握 PHP API 设计与实现的原子化技能

概述

全面的 PHP API 开发技能，涵盖 REST 设计、GraphQL、身份验证策略和 API 文档。

技能参数

输入验证

interface SkillParams {
  topic:
    | "rest"             // RESTful API design
    | "graphql"          // GraphQL with PHP
    | "authentication"   // JWT, OAuth 2.0
    | "documentation"    // OpenAPI, Swagger
    | "versioning"       // API versioning strategies
    | "security";        // Rate limiting, CORS

  level: "beginner" | "intermediate" | "advanced";
  framework?: "laravel" | "symfony" | "slim";
  auth_method?: "jwt" | "oauth2" | "api_key";
}

验证规则

validation:
  topic:
    required: true
    allowed: [rest, graphql, authentication, documentation, versioning, security]
  level:
    required: true
  framework:
    default: "laravel"

学习模块

模块 1：REST API 设计

beginner:
  - Resource naming conventions
  - HTTP methods semantics
  - Status codes usage

intermediate:
  - Pagination patterns
  - Filtering and sorting
  - HATEOAS basics

advanced:
  - Hypermedia APIs
  - Conditional requests
  - Bulk operations

模块 2：身份验证

beginner:
  - API keys
  - Basic auth
  - Token basics

intermediate:
  - JWT implementation
  - Refresh tokens
  - Token revocation

advanced:
  - OAuth 2.0 flows
  - PKCE
  - Scopes and permissions

模块 3：API 安全

beginner:
  - Input validation
  - Output encoding
  - CORS basics

intermediate:
  - Rate limiting
  - Request throttling
  - API versioning

advanced:
  - Security headers
  - Request signing
  - Audit logging

错误处理与重试逻辑

errors:
  VALIDATION_ERROR:
    code: "API_001"
    http_status: 422
    recovery: "Return field-level errors"

  AUTH_ERROR:
    code: "API_002"
    http_status: 401
    recovery: "Check token, suggest refresh"

  RATE_LIMIT_ERROR:
    code: "API_003"
    http_status: 429
    recovery: "Return Retry-After header"

retry:
  max_attempts: 3
  backoff:
    type: exponential
    initial_delay_ms: 100

代码示例

REST 控制器（Laravel）

<?php
declare(strict_types=1);

namespace App\Http\Controllers\Api\V1;

use App\Http\Controllers\Controller;
use App\Http\Requests\StoreUserRequest;
use App\Http\Resources\UserResource;
use App\Models\User;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Response;

final class UserController extends Controller
{
    public function index()
    {
        $users = User::query()
            ->with(['profile'])
            ->filter(request(['search', 'status']))
            ->paginate(request('per_page', 15));

        return UserResource::collection($users);
    }

    public function store(StoreUserRequest $request): JsonResponse
    {
        $user = User::create($request->validated());

        return (new UserResource($user))
            ->response()
            ->setStatusCode(Response::HTTP_CREATED)
            ->header('Location', route('api.v1.users.show', $user));
    }

    public function show(User $user): UserResource
    {
        return new UserResource($user->load('profile'));
    }

    public function destroy(User $user): Response
    {
        $this->authorize('delete', $user);
        $user->delete();

        return response()->noContent();
    }
}

错误响应（RFC 7807）

<?php
declare(strict_types=1);

namespace App\Http\Responses;

final class ProblemDetails
{
    public static function validation(array $errors): array
    {
        return [
            'type' => 'https://api.example.com/errors/validation',
            'title' => 'Validation Error',
            'status' => 422,
            'detail' => 'The request contains invalid data',
            'errors' => $errors,
        ];
    }

    public static function unauthorized(): array
    {
        return [
            'type' => 'https://api.example.com/errors/unauthorized',
            'title' => 'Unauthorized',
            'status' => 401,
            'detail' => 'Authentication required',
        ];
    }
}

JWT 身份验证

<?php
declare(strict_types=1);

namespace App\Services;

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

final class JwtService
{
    public function __construct(
        private readonly string $secret,
        private readonly string $algorithm = 'HS256',
        private readonly int $ttl = 3600,
    ) {}

    public function generate(array $payload): string
    {
        $issuedAt = time();

        return JWT::encode([
            ...$payload,
            'iat' => $issuedAt,
            'exp' => $issuedAt + $this->ttl,
        ], $this->secret, $this->algorithm);
    }

    public function decode(string $token): object
    {
        return JWT::decode($token, new Key($this->secret, $this->algorithm));
    }
}

OpenAPI 规范

openapi: 3.1.0
info:
  title: User API
  version: 1.0.0

paths:
  /api/v1/users:
    get:
      summary: List users
      parameters:
        - name: page
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserCollection'

    post:
      summary: Create user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUser'
      responses:
        '201':
          description: Created

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        name:
          type: string

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - bearerAuth: []

速率限制（Laravel）

<?php
// RouteServiceProvider or bootstrap/app.php
use Illuminate\Cache\RateLimiting\Limit;
use Illuminate\Support\Facades\RateLimiter;

RateLimiter::for('api', function ($request) {
    return Limit::perMinute(60)
        ->by($request->user()?->id ?: $request->ip())
        ->response(function () {
            return response()->json([
                'type' => 'https://api.example.com/errors/rate-limit',
                'title' => 'Too Many Requests',
                'status' => 429,
            ], 429)->header('Retry-After', 60);
        });
});

故障排查

问题	原因	解决方案
CORS 错误	缺少标头	配置 CORS 中间件
JWT 无效	已过期或密钥错误	检查 exp 声明，验证密钥
429 错误	触发速率限制	实施退避策略，缓存响应
资源中出现 N+1 问题	缺少预加载	在控制器中使用 with()

质量指标

指标	目标
响应时间	<200ms P95
错误率	<0.1%
文档	100% 的端点
测试覆盖率	≥90%

用法

Skill("php-api", {topic: "authentication", level: "intermediate"})