kode/http

现代化、高性能的 PHP HTTP 服务端库，支持 PSR-7/PSR-15/PSR-17 标准，多运行时环境（Swoole、Workerman、FPM），深度集成 kode/process、kode/fibers、kode/parallel

3.0.0 2026-08-04 15:51 UTC

Requires

• php: ^8.3
• kode/context: ^2.1
• kode/exception: ^2.0
• psr/http-factory: ^1.0
• psr/http-message: ^1.0|^2.0
• psr/http-server-handler: ^1.0
• psr/http-server-middleware: ^1.0

Requires (Dev)

• guzzlehttp/psr7: ^2.1
• phpunit/phpunit: ^10.0|^11.0|^12.0
• swoole/ide-helper: ^4.15|^5.0
• symfony/var-dumper: ^6.0|^7.0

Suggests

• ext-swoole: 用于 Swoole 协程支持和异步 HTTP 服务器
• guzzlehttp/psr7: 用于 PSR-7 消息实现参考
• kode/fibers: 用于 Fiber 协程调度和并发处理
• kode/parallel: 用于并行任务执行和多线程支持
• kode/process: 用于进程池管理和 Worker 进程
• kode/runtime: 用于协程运行时抽象
• workerman/workerman: 用于 Workerman 多进程支持

Apache-2.0

• Kode Team

• http
• server
• middleware
• async
• coroutine
• psr-7
• swoole
• workerman
• psr-17
• psr-15
• kode
• php8
• php81
• php82
• fiber
• php83
• php84
• php85
• kode-process
• kode-fibers
• kode-parallel

Published on Packagist.org on 2026-08-04 15:52 UTC

README

现代化、高性能的 PHP HTTP 服务端库

Kode\Http 是一个专为 PHP 8.3+ 设计的高性能 HTTP 服务端库，完全兼容 PSR-7/PSR-15/PSR-17 标准。支持 Swoole、Workerman 等协程环境，支持分布式部署，深度集成 kode/context、kode/process、kode/fibers、kode/parallel，打造现代化全栈 PHP 应用。

设计理念：借鉴 ThinkPHP/Laravel/webman 的简洁风格，提供 Request、Response、App 三大核心 API，让开发者无需心智负担即可快速构建高性能 HTTP 服务。

核心特性

• 📦 简洁 API：Request、Response、App 三剑客
• 🎯 PSR-7/15/17 完全兼容：标准化的 HTTP 消息、中间件和工厂实现
• ⚡ 高性能协程支持：无缝对接 Swoole/Workerman，支持 Fiber 协程
• 🔄 多运行时适配：自动检测并适配 FPM、CLI、Swoole、Workerman 环境
• 🌐 分布式部署支持：支持跨机器 Worker、Fiber、并行任务分发
• 🧩 模块化中间件：灵活的中间件管道，支持链式调用
• 🔗 深度集成：与 kode/context、kode/process、kode/fibers、kode/parallel 无缝协作
• 🛡️ 企业级特性：CORS、限流、错误处理、进程管理等开箱即用

环境要求

环境	版本要求
PHP	>= 8.3
PSR-7	^1.0 或 ^2.0
PSR-15	^1.0
PSR-17	^1.0

可选扩展

扩展	说明
ext-swoole	Swoole 协程支持和异步 HTTP 服务器
ext-fiber	PHP Fiber 协程支持
workerman/workerman	Workerman 多进程支持

快速开始

安装

composer require kode/http

最简示例

<?php

require 'vendor/autoload.php';

use Kode\Http\App;
use Kode\Http\Request;
use Kode\Http\Response;

$app = App::create();

$app->get('/api/hello', function() {
    $name = Request::get('name', 'World');
    return Response::success(['greeting' => "你好，{$name}！"]);
});

$app->serve(8080);

核心 API

Request - 请求解析（借鉴 webman）

无需传入 request 参数，直接获取当前请求

// 参数获取（自动从当前请求获取）
Request::get('name');           // GET 参数
Request::post('name');          // POST 参数
Request::json('name');          // JSON body 参数
Request::header('Authorization'); // 请求头
Request::cookie('session_id');  // Cookie

// 字段选择（借鉴 Laravel）
Request::only('name', 'email');           // 仅获取指定字段
Request::except('password', 'token');     // 排除指定字段

// 判断存在（借鉴 ThinkPHP）
Request::has('name');            // 参数是否存在
Request::missing('token');       // 参数是否缺失

// 获取所有参数
Request::all();                  // 合并 query + body

// 请求信息
Request::ip();                   // 客户端 IP
Request::method();              // 请求方法
Request::path();                // 请求路径
Request::isAjax();              // 是否 AJAX 请求
Request::isJson();              // 是否 JSON 请求
Request::isMobile();            // 是否移动端
Request::isGet();               // 是否 GET 请求
Request::isPost();              // 是否 POST 请求

// 其他
Request::userAgent();           // User-Agent
Request::referer();             // 来源页面
Request::language();            // Accept-Language
Request::time();                // 请求时间戳
Request::file('avatar');        // 上传文件
Request::server('REQUEST_TIME'); // 服务器变量

Response - 响应构建（链式调用）

// JSON 响应
Response::json(['data' => 'value']);
Response::json(['data' => 'value'], 1);  // 带业务码

// 业务响应（借鉴 Laravel）
Response::success(['id' => 1], '操作成功');
Response::fail('用户名或密码错误', 'E1001');

// HTTP 错误
Response::error(404, 'Not Found');
Response::error(500, 'Internal Server Error', 'E1500');

// 其他响应类型
Response::text('Hello World');
Response::html('<h1>Title</h1>');
Response::xml('<root></root>');
Response::empty();                // 204 空响应
Response::redirect('/login');    // 302 重定向
Response::download('/path/file.pdf');

// 链式调用
Response::success(['data' => $data])
    ->status(201)
    ->header('X-Custom', 'value')
    ->withCors()
    ->withCache(3600)
    ->withSecurity()
    ->send();

App - 应用构建器

use Kode\Http\App;
use Kode\Http\Request;
use Kode\Http\Response;

$app = App::create(debug: true);

// 添加中间件
$app->use(function($req, $next) {
    $start = microtime(true);
    $response = $next->handle($req);
    return $response->withHeader('X-Execution-Time', sprintf('%.2fms', (microtime(true) - $start) * 1000));
});

// 路由注册
$app->get('/api/users', function() {
    return Response::success(['users' => [
        ['id' => 1, 'name' => '张三'],
        ['id' => 2, 'name' => '李四'],
    ]]);
});

$app->post('/api/users', function() {
    $name = Request::json('name');
    $email = Request::json('email');

    if (empty($name)) {
        return Response::fail('用户名不能为空', 'E1001', 400);
    }

    return Response::success(['id' => rand(1000, 9999)], '创建成功');
});

// 路由参数
$app->get('/api/users/{id}', function() {
    $id = Request::param('id');   // 路由参数（等价 Request::attr('id')）
    return Response::success(['id' => $id]);
});

$app->delete('/api/users/{id}', function() {
    return Response::success(null, '删除成功');
});

// 路由组
$app->group('/api/v1', function($api) {
    $api->get('/status', fn() => Response::success(['status' => 'ok']));
    $api->post('/action', fn() => Response::success());
});

// HTTP 方法
$app->patch('/api/users/{id}', fn() => Response::success());
$app->options('/api/users', fn() => Response::empty());
$app->any('/api/health', fn() => Response::success());

// 运行
$app->serve(8080);

PSR-7 消息实现

类	说明
Request	HTTP 请求消息，包含方法、URI、头部、协议版本
Response	HTTP 响应消息，包含状态码、原因短语、头部、正文
ServerRequest	服务端请求，继承 Request 并添加服务端特性
Stream	流式正文，支持读取、写入、定位等操作（自研实现）
Uri	URI 实现，支持解析和构建 URI 各部分

PSR-15 中间件

v3.0 起中间件管道为无状态、可重入实现（MiddlewarePipeline + PipelineRunner）， 同一实例可在 Swoole 协程 / Fiber 并发环境下安全复用，不再持有请求级可变索引。

中间件	说明
MiddlewareDispatcher	核心中间件调度器，管理中间件栈并执行调度
MiddlewarePipeline	无状态管道实现，支持链式中间件调用
PipelineRunner	每次 dispatch 创建独立执行游标（可重入）
CallableMiddleware	将可调用对象转换为中间件
CorsMiddleware	CORS 跨域处理
RateLimitMiddleware	请求限流
JsonErrorHandlerMiddleware	JSON 错误处理
BodyParser	自动解析 JSON / 表单 / XML 请求体（PHP 8.3 json_validate）
RequestId	生成 / 复用请求 ID（X-Request-Id），便于链路追踪
ResponseTime	注入 X-Response-Time 响应耗时头（hrtime 纳秒计时）
Compression	按 Accept-Encoding 协商 gzip / deflate 压缩响应体
SecurityHeaders	注入 X-Content-Type-Options / X-Frame-Options / Referrer-Policy 等安全头

集成组件

组件	说明
ProcessWorkerMiddleware	进程工作单元，集成 kode/process，支持分布式
FiberCoroutineMiddleware	Fiber 协程，集成 kode/fibers，支持分布式
ParallelMiddleware	并行处理，集成 kode/parallel，支持分布式

分布式部署

概述

Kode\Http 支持分布式部署场景，可以通过简单的配置启用分布式模式：

use Kode\Http\Integration\DistributedConfig;
use Kode\Http\Integration\ProcessWorkerMiddleware;
use Kode\Http\Integration\FiberCoroutineMiddleware;
use Kode\Http\Integration\ParallelMiddleware;

分布式配置

$config = new DistributedConfig('node-1');
$config->setEnabled(true);
$config->setNodes([
    'node-1' => ['host' => '192.168.1.1', 'port' => 8080, 'weight' => 1],
    'node-2' => ['host' => '192.168.1.2', 'port' => 8080, 'weight' => 1],
]);
$config->setLoadBalanceStrategy('round_robin');
$config->setCallTimeout(30.0);
$config->setMaxRetries(3);

分布式 Worker（kode/process 集成）

$worker = new ProcessWorkerMiddleware(0, true, [
    'pool_size' => 4,
    'enable_stats' => true,
    'distributed' => [
        'enabled' => true,
        'node_id' => 'worker-1',
        'nodes' => [
            'worker-1' => ['host' => '192.168.1.1', 'port' => 8080],
            'worker-2' => ['host' => '192.168.1.2', 'port' => 8080],
        ],
    ],
]);

$app->use($worker);

分布式 Fiber 协程（kode/fibers 集成）

$fiber = new FiberCoroutineMiddleware(10, 2048, [
    'timeout' => 30,
    'distributed' => [
        'enabled' => true,
        'node_id' => 'fiber-1',
        'nodes' => [
            'fiber-1' => ['host' => '192.168.1.1', 'port' => 8081],
            'fiber-2' => ['host' => '192.168.1.2', 'port' => 8081],
        ],
    ],
]);

$app->use($fiber);

分布式并行处理（kode/parallel 集成）

$parallel = new ParallelMiddleware(10, [
    'distributed' => [
        'enabled' => true,
        'node_id' => 'parallel-1',
        'nodes' => [
            'parallel-1' => ['host' => '192.168.1.1', 'port' => 8082],
            'parallel-2' => ['host' => '192.168.1.2', 'port' => 8082],
        ],
        'load_balance_strategy' => 'least_load',
    ],
]);

$app->use($parallel);

项目结构

src/
├── Psr7/                          # PSR-7 实现
│   ├── Message/                   # 消息类（Request/Response/ServerRequest）
│   ├── Factory/                   # PSR-17 工厂（含 Psr17Factory 聚合工厂）
│   ├── Trait/                     # 可复用 Trait（RequestTrait/ResponseTrait）
│   ├── Stream.php                 # 自研流实现
│   ├── Uri.php                    # URI 实现
│   └── UploadedFile.php           # PSR-7 上传文件
├── Routing/                       # 路由子系统
│   ├── Router.php                 # 静态哈希 + 动态正则两级匹配，区分 404/405
│   ├── Route.php                  # 路由定义（参数约束 / 可选参数 / 命名）
│   ├── RouteResult.php            # 匹配结果（FOUND/NOT_FOUND/METHOD_NOT_ALLOWED）
│   └── RouteRunner.php            # 路由执行器（最终处理器，参数注入 + 返回值归一化）
├── Middleware/                    # PSR-15 中间件
│   ├── MiddlewareInterface.php
│   ├── MiddlewareDispatcher.php
│   ├── MiddlewarePipeline.php
│   ├── PipelineRunner.php         # 无状态可重入执行游标
│   ├── CallableMiddleware.php
│   ├── CorsMiddleware.php
│   ├── RateLimitMiddleware.php
│   ├── JsonErrorHandlerMiddleware.php
│   ├── BodyParser.php             # 请求体解析
│   ├── RequestId.php              # 请求 ID
│   ├── ResponseTime.php           # 响应耗时
│   ├── Compression.php            # 响应压缩
│   └── SecurityHeaders.php        # 安全响应头
├── Integration/                   # 集成组件
│   ├── DistributedConfig.php
│   ├── ProcessWorkerMiddleware.php
│   ├── FiberCoroutineMiddleware.php
│   └── ParallelMiddleware.php
├── Server/                       # 服务端适配器
├── Exception/                     # 异常
├── App.php                       # 应用构建器
├── Request.php                   # 请求助手（kode/context 隔离）
├── Response.php                  # 响应助手（链式 + 返回值归一化）
├── Emitter.php                   # PSR-7 响应发射器（分块输出）
├── Status.php                    # HTTP 状态码枚举（类型安全 + 原因短语）
├── Method.php                    # HTTP 方法枚举（ROUTABLE/isSafe/isIdempotent）
├── Kode.php                      # 框架入口
└── functions.php                 # 辅助函数（指向 Psr17Factory）

测试

./vendor/bin/phpunit
./vendor/bin/phpunit --coverage-html coverage

与其他 Kode 包的关系

kode/http
    │
    ├── kode/context     # 请求上下文传递和管理
    │
    ├── kode/runtime     # 协程运行时抽象
    │
    ├── kode/fibers      # Fiber 协程调度
    │       │
    │       └── kode/parallel  # 并行任务处理
    │
    └── kode/process     # 进程管理和 Worker
            │
            └── kode/http-client  # HTTP 客户端（统一到 PSR-7 抽象）

版本历史

• v3.0.0 - PHP 8.3+ 最低支持；重写路由器（静态哈希 + 动态正则、区分 404/405、命名路由 URL 生成）、无状态可重入中间件管道；新增 Status/Method 枚举、Emitter、BodyParser/RequestId/ResponseTime/Compression/SecurityHeaders 中间件；修复 PSR-7 大小写不敏感头查找告警
• v2.1.0 - 增强 App 应用构建器，支持路由参数提取
• v2.0.0 - 借鉴 ThinkPHP/Laravel/webman 重构 API
• v1.5.0 - 增强 Request 请求助手方法
• v1.4.0 - 新增 App、Request、Response 统一 API
• v1.3.0 - 适配 kode/exception ^2.0
• v1.0.0 - 初始版本，PSR-7/15/17 基础实现

License

Apache-2.0