README

dleno/common-core 是 Dleno Hyperf 3.1 项目的公共核心包，负责沉淀 HTTP/RPC/Model/AMQP/AsyncQueue/WebSocket 等基础能力，以及项目通用工具、全局函数、异常输出、日志输出、分布式锁和示例模板。

它的定位是“框架基座 + 业务可接入的公共组件”，不是一个完整业务应用。业务项目只需要安装包、补齐少量 DI 绑定和业务策略，就可以复用统一的请求解析、输出格式、模型能力、队列封装、WebSocket 连接管理和在线检查能力。

环境要求

PHP >= 8.1
Swoole >= 5.0
Hyperf ~3.1
ext-curl
WebSocket 功能依赖 Redis 7.4+ 的 HEXPIRE 能力

启用 WebSocket 服务时，启动前会校验：

server.mode 必须是 SWOOLE_BASE，否则直接终止启动。
Redis 可达但不支持 HEXPIRE 时直接终止启动。
Redis 暂时不可达时只输出 WARN 放行，避免启动编排中的短暂网络抖动误杀服务；运行时仍要求 Redis 7.4+ 可用。

安装

composer require dleno/common-core:^3.1

安装后包内 ConfigProvider 会自动生效：

扫描 src/ 下的注解。
自动加载 src/common/Functions.php 全局函数。
通过 dleno/hyperf-env-multi 显式加载环境文件：先加载 .env，再按 APP_ENV 加载 .env.<APP_ENV>，环境文件中的同名变量以后者为准。
注入部分基础 dependencies。
按 ENABLE_HTTP / ENABLE_WS 自动注入 HTTP / WS 基础中间件。
提供 WebSocket 配置发布模板，可通过 vendor:publish 写入 config/autoload/websocket.php。

发布配置：

php bin/hyperf.php vendor:publish dleno/common-core

接入清单

HTTP 请求对象绑定

Hyperf 自身也会绑定 RequestParserInterface 和 RequestInterface，因此这两个绑定需要放在业务项目 config/autoload/dependencies.php，确保优先级稳定：

return [
    Hyperf\HttpMessage\Server\RequestParserInterface::class
        => Dleno\CommonCore\Core\Request\RequestParser::class,
    Hyperf\HttpServer\Contract\RequestInterface::class
        => Dleno\CommonCore\Core\Request\Request::class,
];

CoreMiddleware 和 DispatcherFactory 已由 common-core 的 ConfigProvider 注入，通常不需要业务项目重复绑定。

HTTP 模块前置中间件绑定

common-core 会在 HTTP InitMiddleware 之后自动注册 AbstractModuleBeforeMiddleware，并默认绑定到包内 DefaultModuleBeforeMiddleware。默认实现会按 config('app.api_check_sign') / config('app.api_data_crypt') 执行签名校验和请求解密，checkAuth() 为 no-op，checkReplay() 返回 true 放行。

业务需要登录校验、防重放或自定义签名参数时，推荐继承 DefaultModuleBeforeMiddleware，只覆写需要的钩子，并在业务项目 config/autoload/dependencies.php 中覆盖抽象基类绑定：

return [
    Dleno\CommonCore\Middleware\Http\AbstractModuleBeforeMiddleware::class
        => App\Middleware\AppModuleBeforeMiddleware::class,
];

如未覆盖该绑定，会使用包内默认实现：签名/解密仍按配置开关执行，但不会做业务登录校验或防重放拦截。

参考实现见：

examples/Middleware/AppModuleBeforeMiddleware.php

异常处理器配置

异常处理链顺序敏感，DefaultExceptionHandler 会兜底并终止后续传播。因此 common-core 不通过 ConfigProvider 自动注入 exceptions.handler，而是提供 ExceptionHandlerConfig 让业务项目在 config/autoload/exceptions.php 中显式生成默认链，并保留业务 handler 的插入位置：

use Dleno\CommonCore\Exception\ExceptionHandlerConfig;

return [
    'handler' => ExceptionHandlerConfig::defaultHandlers(
        httpCommonHandlers: [
            App\Exception\Handler\BusinessCommonExceptionHandler::class,
        ],
        wsCommonHandlers: [
            App\WebSocket\Exception\Handler\BusinessCommonWsExceptionHandler::class,
        ],
        httpBeforeDefault: [
            App\Exception\Handler\BusinessOutputExceptionHandler::class,
        ],
        wsBeforeDefault: [
            App\WebSocket\Exception\Handler\BusinessWsOutputExceptionHandler::class,
        ],
    ),
];

httpCommonHandlers / wsCommonHandlers 会插入到 common-core 的 CommonExceptionHandler 之后，用于回滚、审计、上下文清理等公共前置处理，不应调用 stopPropagation()；httpBeforeDefault / wsBeforeDefault 会插入到对应协议的 DefaultExceptionHandler 之前，用于业务输出类 handler。未启用 ENABLE_HTTP / ENABLE_WS 时不会生成对应 server 的异常链。

WebSocket 业务策略绑定

WebSocket 的连接维度属于业务决策，common-core 不提供默认绑定策略。业务项目必须在 dependencies.php 中绑定 WsBindStrategyInterface：

return [
    Dleno\CommonCore\Websocket\Contract\WsBindStrategyInterface::class
        => App\WebSocket\Bind\DefaultWsBindStrategy::class,
];

WsHookInterface 已有 no-op 默认实现，业务不需要身份解析、握手校验或生命周期钩子时可以不覆盖；需要接入登录态、握手鉴权、open/close/heartbeat/message/send 等业务逻辑时再绑定：

return [
    Dleno\CommonCore\Websocket\Contract\WsHookInterface::class
        => App\WebSocket\Hook\AppWsHook::class,
];

参考实现见：

examples/WebSocket/Bind/DefaultWsBindStrategy.php
examples/WebSocket/Bind/MultiDimWsBindStrategy.php
examples/WebSocket/Hook/AppWsHook.php

核心能力

HTTP 基座

相关目录：

src/Base/BaseCoreController.php
src/Middleware/Http
src/Core/Request
src/Core/Route
src/Annotation
src/Aspect

主要能力：

Controller 自动注入对应 Service。
successData() 统一返回结构。
checkParams() 参数校验。
LockCheckTrait 提供分布式锁辅助。
OutputHtml、OutputNoLog、OutputNotFormat 等注解控制输出格式、日志和字段格式化。
HTTP 输出切面自动记录响应日志，并在 API_DATA_CRYPT 开启时加密响应体。
HTTP 请求初始化、语言/时区/traceId 等上下文处理。
路由分发增强和请求对象替换。
AutoController 请求方式控制：方法级 #[AllowMethods] 优先，其次类级 AutoController(defaultMethods)、config('app.default_allow_methods')、默认 ['POST', 'GET']；包含 GET 时自动补 HEAD，OPTIONS 预检由 InitMiddleware 统一处理。
模块前置中间件提供签名校验、请求解密、登录校验和防重放钩子。AbstractModuleBeforeMiddleware 封装流程，DefaultModuleBeforeMiddleware 提供默认钩子实现，业务通常继承默认实现后在 dependencies.php 绑定抽象基类来接管。该中间件只处理已命中路由（FOUND）；NOT_FOUND / METHOD_NOT_ALLOWED 会放行给管线末端 CoreMiddleware 返回 404 / 405，避免未知路由被误判为签名错误。

示例：

examples/Http
examples/Middleware
examples/Config

异常与输出

相关目录：

src/Exception
src/Tools/OutPut.php
src/Tools/Output
src/Tools/Logger.php

主要能力：

HTTP/RPC 常用异常处理器。
ExceptionHandlerConfig 生成 HTTP / WS 默认异常链，并支持业务公共前置 handler、兜底前输出 handler 插入到固定位置。
统一 JSON 输出。
API/RPC/Error 输出日志封装。
HTTP/WS Controller 响应日志切面。
按渠道输出 stdout、system、api、sql、business 日志。
错误输出可读取业务 config/autoload/dingtalk.php 的 dingtalk.trace 配置发送异常追踪通知。

Model 与数据库

相关目录：

src/Model
src/Db

主要能力：

BaseModel 统一模型基类。
自定义 EloquentBuilder，支持分页、分组统计、批量插入更新、全文检索等项目增强方法。
支持按年/月/日/周/固定数量分表。
findById()、updateById()、deleteById() 按主键路由到对应分表。
withTable() 支持指定分表后缀查询。
模型生成时保持 decimal 精度处理。

示例：

examples/Model/BaseModel.php
examples/Model/Test.php
examples/Model/TestSplit.php

AMQP

相关目录：

src/Base/Amqp
src/Tools/Amqp

主要能力：

BaseProducer、BaseConsumer 封装 Hyperf AMQP。
支持延迟交换机。
支持死信交换机、死信路由、消息 TTL、队列 TTL。
支持生产者确认。
支持静态队列和按服务器动态 routingKey / queue。

示例：

examples/Amqp
examples/Amqp/Dynamic

AsyncQueue

相关目录：

src/Base/AsyncQueue
src/Tools/AsyncQueue

主要能力：

BaseJob 统一队列 Job 基类。
BaseQueueConsumer 统一消费进程基类。
BaseDriverFactory 支持动态队列驱动配置。
AsyncQueue::push() 会按 Job 的 queue 自动选择对应 driver。
支持静态队列和按服务器动态队列。

示例：

examples/AsyncQueue
examples/AsyncQueue/Dynamic

WebSocket

相关目录：

src/Websocket
publish/websocket.php

主要能力：

WebSocket 握手鉴权中间件。
WS Controller 注解和消息路由。
生命周期 Hook：握手前/中/后、open、close、heartbeat、message、send 等。
连接绑定策略：bindDimensions()、addressableDimensions()、onlineCheckDimensions()、uniqueDimensions()。
按维度推送：单 fd、批量 fd、广播、按业务维度推送。
连接唯一性：支持同账号单连接、同账号同设备单连接等踢旧策略。
实时在线检查：checkRealtimeOnlineByDim()，适合小批量、强实时、unique 维度。
心跳在线检查：checkHeartbeatOnlineByDim()，基于 Redis 7.4+ HEXPIRE 和 presence bucket 索引，适合大批量心跳级判断。
全量心跳在线快照：checkHeartbeatOnlineAllByDim()，适合后台/统计类低频场景。
per-server 实时消息队列和可选独立控制队列，避免在线核验/断连阻塞真实消息下发。

维度配置建议：

addressableDimensions() 用于“能不能按这个维度推送/寻址”。
onlineCheckDimensions() 用于“能不能按这个维度做心跳在线检查”。
uniqueDimensions() 用于“这个维度是否单连接/踢旧”。
低基数维度如 device_type=ios/android/h5 可以用于推送寻址，但不应放入 onlineCheckDimensions()，否则单个 value 可能挂大量连接，在线检查会变重。
高基数且单 value 连接数可控的维度，如 account_id，更适合做在线检查。

WebSocket 配置见 config/autoload/websocket.php，模板来源为 publish/websocket.php。重点配置：

key_prefix: WS Redis key 前缀。
local_enable: local 环境是否启用 WS 常驻进程。
server_set_cache_ms: 在线服务器集合短缓存。
presence_bucket_num: 心跳 presence 索引 bucket 数。
realtime_online.max / realtime_online.timeout: 实时在线核验批量上限与等待超时。
queue: 实时消息队列消费进程与并发配置。
dedicated_queue: 独立控制队列配置。

示例：

examples/WebSocket

JsonRpc / MQ RPC

相关目录：

src/JsonRpc

主要能力：

JSON-RPC 客户端代理。
MQ 异步 RPC 封装。
MQ RPC 失败重试和异常链保留。

示例：

examples/Tools/UsageExamples.php

工具类

相关目录：

src/Tools
src/Traits
src/common/Functions.php

常用能力：

DcsLock: Redis 分布式锁，支持等待、自动续期、Lua 解锁。
HttpClient: 协程内走 Swoole Coroutine Client，非协程内走 curl。
- postInternal 使用进程内 Swoole HTTP 连接池；getPooled/postPooled/putPooled 为渠道申请、查询的显式接入，原 get/post/put/delete/patch 不变。池按 origin 和传输设置隔离，每次独占连接，不共享请求 Header、正文或 Cookie。
- 无连接数上限、无抢连接队列；空闲连接不足立即创建。无探活池通过密集业务逐步建立保底，保底内轮换复用；流量间隔不足以在空闲有效期内维持保底时，优先复用健康连接；参考最近两次间隔，避免门限两侧抖动造成反复冷连。补足保底的新建失败后，后续独立业务在 2 秒内优先复用已有健康连接，当前失败请求不重发。旧 max_connections/wait_timeout 不再使用。min_connections 统计真实已连接的忙碌与空闲连接，不要求始终保留指定数量的空闲连接。默认内部 5、渠道 2。
- http_client.internal_pool / http_client.driver_pool 可设置 min_connections、connect_timeout（默认 5 秒）、max_idle_time（默认 60 秒）、heartbeat（默认 20 秒）、max_lifetime（默认 600 秒，0 关闭）。连接自建立起在 max_lifetime 的最后 10% 区间内（随机错开，避免同批连接同时重建），完成当前请求即关闭、不再放回池中，空闲的到期连接由后台扫描关闭，后续业务或安全探活新建连接，使 DNS 缓存更新后的地址有机会生效（不强制清除 DNS 缓存）；进行中的请求不被打断，也不重发。借出时和后台每秒扫描都检查空闲期限；后台回收超出保底且超过空闲期限的连接；无安全健康路径时，保底连接也遵守空闲期限，由后续正常业务补建；健康探活不延长业务空闲期限。所有池内时间间隔／轮次使用单调时钟 hrtime，不受系统墙钟回拨影响；业务签名时间戳不变。配置在首次建立池时读取，变更须重启进程。
- 内部默认 health_path='/'、health_method='GET'，调用方须保证该路径安全。渠道默认没有健康路径，靠实际业务逐步建立保底连接；远端关闭或长时间无业务时不保证有效数量，不发送支付、查询或 Token 心跳。URL 主机名与健康配置 origin 键均按小写匹配。仅对已确认安全且可保持连接的目标配置 health_targets['https://api.example.com:443']=['path'=>'/health','method'=>'HEAD']；仅支持 GET/HEAD，不支持的方法按未配置探活处理，路径不得带查询、片段或其他 origin。可将内部 health_path 设为 null 禁用探活。
- 维护只借用空闲连接，补建失败按轮次采用 2/4/8/16/30 秒退避，同一轮多条失败只计一次；已有连接的心跳不随补建退避停止，也不改变补建退避；上一批补建全部结束前不派发新批次，防错峰超时架空退避；探活响应必须完整且连接可继续使用，HTTP 状态本身不是业务或健康成功判断。ElasticHttpPool::statistics() 提供进程内 live/idle/busy、保底满足情况、补建失败轮数（maintenanceFailures）和维护运行状态。维护协程创建遇到容量上限时不阻断当前业务，计数／连接正常归还，后续业务再尝试启动。维护异常按 ERROR 记录，不永久关闭池；下一次业务可重启维护并继续复用健康连接。新建业务连接成功或业务补足内部保底时清除历史补建退避，旧探活结果不回写该状态。随 worker 退出关闭空闲连接，业务连接在请求完成后关闭。
- 禁用重定向及底层重发（max_retries=0，不允许配置覆盖）；正常 4xx/5xx 保留状态与正文。Swoole 6.1 返回 1xx 时无法继续收取该请求的最终响应，按结果未确认返回 errCode=-1 并关闭连接，不回池、不重发。失败连接及有残留可读数据的空闲连接立即关闭，不允许 TLS EOF 后被再次判定可用，本次请求不补发；协程池多值 Header 按 HTTP 列表合并（Cookie 分号、其他逗号），默认头按大小写无关覆盖；HTTP 方法按合法 token 检查，阻止请求行空格／换行注入；Header 的 CR/LF 在发送前拒绝，避免破坏请求边界；下一次独立业务可新建。业务配置／代码异常继续抛出，后台维护异常按 ERROR 记录。请求超时、读写超时、同步收响应、keep-alive、Header 小写和零重试不允许 transport 配置覆盖。内部协程响应头维持多值数组格式，非协程 cURL 分支保持原格式。内部 TLS 强制验证证书和主机名；普通渠道默认同样验证，SDK 用 requestSdkPooled 保留自身 Header 和显式 TLS 设置。
- HTTPS 默认验证受信任证书链及目标主机名：连接池、普通协程请求和非协程 cURL 三条路径一致；不允许自签名证书。使用系统 CA，无需逐个保存渠道证书。cURL 的显式 verify 参数和池的显式传输配置仍按调用契约保留，但不能将关闭校验作为一般网络错误的兜底。连接超时 5 秒与校验开关独立。SDK 专有传输仍须核对其自身配置。
- 非协程路径保持原生 curl 单次请求，不使用连接池。签名、AES/RSA、nonce、业务身份由调用方负责。应用接入前先发布包含新方法的本包再更新依赖，不能先发布调用新方法的应用。
- php examples/internal-http-pool-check.php /path/to/app/vendor/autoload.php 覆盖 TCP 复用、64 路并发、Header/body/Cookie 隔离、状态、禁用重定向、超时／断连不重发；elastic-http-pool-check.php 覆盖真实活动保底、64 路扩容、超额回收和内部预热。http-pool-capacity-check.php 在实际框架错误处理器下覆盖协程容量耗尽及恢复；http-pool-tls-check.php 覆盖正常 TLS 1.3 复用和无 close_notify 的 TCP FIN 重复检查。http-pool-floor-check.php 覆盖补足保底失败后独立请求仍使用健康连接；http-pool-maintenance-check.php 注入协调器异常，覆盖维护故障记录、恢复和 TCP 复用。http-pool-stagger-check.php 以错峰关闭／延迟响应验证补建批次不重叠及退避正确。http-pool-clock-check.php 模拟墙钟回拨，确认池内时序与 TCP 复用不受影响。http-pool-timeout-check.php 覆盖同一 TCP 上长短请求的独立超时。均仅回环，不代表生产吞吐或渠道验收。
OpenSslCrypt: AES/DES 对称加解密。
OpenSslRsa / OpenSslRsa2: RSA 分块加解密。两者协议不同——OpenSslRsa 密文为 hex（偏长），OpenSslRsa2 密文为 base64（约短一半）。接口加密的 Client-Key（AES 密钥）解密走 OpenSslRsa2，客户端须使用同款算法加密。
CheckVal / CheckParams: 常用格式校验和参数校验。
Client / Server: 客户端信息、IP、设备、语言、路由、traceId 等辅助。
ArrayTool、Strings、TimeTool、Distribution 等工具。
ObjectAttribute: 对象属性填充/导出辅助。

示例：

examples/Tools/UsageExamples.php

examples 目录

examples/ 是使用示例集合，不会随包安装自动执行。

安全边界：

composer.json 只 autoload src/，不加载 examples/。
ConfigProvider 只扫描 src/，不扫描 examples/。
示例命名空间为 Dleno\CommonCore\Examples\...，不会占用业务 App\...。
AMQP Consumer 示例的 isEnable() 保留 AMQP_ENABLE 前置门禁；Crontab 示例保留 ENABLE_CRONTAB 前置门禁；随后都会拦截 local 环境并默认 return false，避免误扫后真实执行。
HTTP Controller、WS Controller 示例刻意不直接声明 #[AutoController]、#[WsController]，复制到业务项目后再按注释启用。

使用方式：

复制需要的示例到业务项目 app/ 下对应目录。
修改 namespace，例如改成 App\WebSocket\Bind。
根据业务把 isEnable() 改成自己的启用条件；复制后建议保留 AMQP_ENABLE / ENABLE_CRONTAB 等功能开关和 local 环境强制关闭判断。
不要直接把 vendor/dleno/common-core/examples 加入业务注解扫描路径。

常用环境变量

基础开关：

APP_NAME: 应用名，Redis key 前缀等通用配置会使用。
APP_ENV: 当前运行环境；存在 .env.<APP_ENV> 时会覆盖 .env 中的同名变量。
IS_PROD: 强制判定为正式环境；未设置时 config('app_env') === 'prod' 也会视为正式环境。
ENABLE_HTTP: 是否启用 HTTP server 相关基础中间件。
ENABLE_WS: 是否启用 WebSocket 相关进程和中间件。
HTTP_INIT_MIDDLEWARE_ENABLE: 是否自动注入 HTTP 初始化中间件和模块前置中间件，默认开启。
WS_AUTH_MIDDLEWARE_ENABLE: 是否自动注入 WS 鉴权中间件，默认开启。
LOG_MAX_FILES: 默认日志文件保留数量。

WebSocket：

WS_KEY_PREFIX
WS_LOCAL_ENABLE
WEBSOCKET_COMPRESSION
WS_SERVER_SET_CACHE_MS
WS_PRESENCE_BUCKET_NUM
WS_REALTIME_ONLINE_MAX
WS_REALTIME_ONLINE_TIMEOUT
WS_CONSUMER_PROCESSES
WS_CONSUMER_LIMIT
WS_CONSUMER_MAX_MESSAGES
WS_DEDICATED_QUEUE_ENABLE
WS_DEDICATED_PROCESSES
WS_DEDICATED_LIMIT
WS_DEDICATED_MAX_MESSAGES

连接池与外部服务：

DB_HOST
DB_MIN_CONNECTION / DB_MAX_CONNECTION
DB_CONNECT_TIMEOUT / DB_WAIT_TIMEOUT
DB_HEARTBEAT / DB_MAX_IDLE_TIME
DB_READ_HOST / DB_WRITE_HOST
DB_READ_MIN_CONNECTION / DB_READ_MAX_CONNECTION
DB_READ_CONNECT_TIMEOUT / DB_READ_WAIT_TIMEOUT
DB_READ_HEARTBEAT / DB_READ_MAX_IDLE_TIME
DB_WRITE_MIN_CONNECTION / DB_WRITE_MAX_CONNECTION
DB_WRITE_CONNECT_TIMEOUT / DB_WRITE_WAIT_TIMEOUT
DB_WRITE_HEARTBEAT / DB_WRITE_MAX_IDLE_TIME
REDIS_MIN_CONNECTION / REDIS_MAX_CONNECTION
REDIS_CONNECT_TIMEOUT / REDIS_WAIT_TIMEOUT
REDIS_HEARTBEAT / REDIS_MAX_IDLE_TIME
AMQP_CONNECTION / AMQP_MIN_CONNECTION / AMQP_MAX_CONNECTION
AMQP_CONNECT_TIMEOUT / AMQP_WAIT_TIMEOUT
AMQP_READ_WRITE_TIMEOUT / AMQP_HEARTBEAT
AMQP_MAX_IDLE_CHANNELS
CONSUL_SERVER_URI
RPC_CONNECT_TIMEOUT / RPC_RECV_TIMEOUT
RPC_MIN_CONNECTION / RPC_MAX_CONNECTION
RPC_WAIT_TIMEOUT / RPC_HEARTBEAT / RPC_MAX_IDLE_TIME

测试与校验

本包当前 composer test 执行 PHP 语法检查，覆盖 src、publish、examples：

composer test

Composer 文件校验：

composer validate --strict

目录结构

src/                  核心源码
publish/              可发布配置模板
examples/             使用示例,不会自动加载或执行
.github/workflows/    Release 等自动化工作流

设计原则

核心协议和运行时约束放在 common-core 内统一维护。
业务差异通过策略、Hook、配置和示例复制接入。
WebSocket 低层队列、注册、presence、在线检查逻辑不建议业务继承改写。
启动期能确定的错误尽量 fail-fast，但 Redis 暂时不可达只告警，避免误杀编排过程中的短暂抖动。
示例代码只作为模板，不作为运行时功能的一部分。

dleno / common-core

Package info

Security

Statistics

README

环境要求

安装

接入清单

HTTP 请求对象绑定

HTTP 模块前置中间件绑定

异常处理器配置

WebSocket 业务策略绑定

核心能力

HTTP 基座

异常与输出

Model 与数据库

AMQP

AsyncQueue

WebSocket

JsonRpc / MQ RPC

工具类

examples 目录

常用环境变量

测试与校验

目录结构

设计原则