config-files.md

配置文件规范

config/ 目录结构

config/
├── config.php           # 框架核心配置（极少修改）
├── container.php         # 容器配置（绑定接口到实现）
├── dependencies.php     # 依赖配置（服务定义）
├── dev.php              # 开发环境配置
├── prod.php             # 生产环境配置
└── autoload/            # 业务配置（按功能分文件）
    ├── databases.php     # 数据库连接配置
    ├── middlewares.php   # 中间件注册
    ├── annotations.php   # 注解扫描路径
    ├── services.php      # 业务服务注册
    ├── cache.php         # 缓存配置
    ├── redis.php         # Redis 配置
    └── rpc.php           # RPC 服务配置

autoload/*.php 优先级

config/autoload/ 下的文件会覆盖 config/ 下的同名配置，实现「环境区分」或「本地覆盖」。

常用配置文件示例

databases.php

<?php
use Hyperf\Database\ConnectionInterface;

return [
    'default' => 'default',
    'connections' => [
        'default' => [
            'driver'    => 'mysql',
            'host'      => env('DB_HOST', '127.0.0.1'),
            'port'      => env('DB_PORT', 3306),
            'database'  => env('DB_DATABASE', 'hyperf'),
            'username'  => env('DB_USERNAME', 'root'),
            'password' => env('DB_PASSWORD', ''),
            'charset'   => 'utf8mb4',
            'collation' => 'utf8mb4_unicode_ci',
            'prefix'    => '',
            'pool'      => [
                'min_connections' => 1,
                'max_connections' => 10,
                'connect_timeout' => 10.0,
                'wait_timeout'    => 3.0,
                'heartbeat'      => -1,
                'max_idle_time'  => 60.0,
            ],
        ],
    ],
];

middlewares.php

<?php
return [
    'http' => [
        App\Middleware\CorsMiddleware::class,
        App\Middleware\AuthMiddleware::class,
    ],
    // 'websocket' => [...],
];

services.php

<?php
use App\Service\Impl\UserServiceImpl;

return [
    // 绑定接口到实现（配合 #[Inject] 使用）
    App\Service\UserServiceInterface::class => UserServiceImpl::class,
];

container.php

<?php
use Hyperf\Di\Container;
use Psr\Container\ContainerInterface;

return [
    // 直接绑定实例
    SomeInterface::class => new SomeImplementation(),

    // 绑定工厂
    OtherInterface::class => [OtherFactory::class, 'make'],
];

redis.php

<?php
return [
    'default' => [
        'host'     => env('REDIS_HOST', '127.0.0.1'),
        'port'     => env('REDIS_PORT', 6379),
        'password' => env('REDIS_PASSWORD', null),
        'db'       => 0,
        'pool'     => [
            'min_connections' => 1,
            'max_connections' => 10,
        ],
    ],
    // 多 Redis 实例
    'cache' => [
        'host'     => '127.0.0.1',
        'port'     => 6379,
        'db'       => 1,
        'pool'     => ['max_connections' => 5],
    ],
];

配置读取方式

<?php
// 全局函数（简单场景）
$value = config('databases.default.host');

// 注解注入（类型安全，推荐）
#[ConfigBean("databases")]
protected array $dbConfig;

// 单例中的配置类
use Hyperf\Di\Annotation\Inject;
use Hyperf\Contract\ConfigInterface;

#[Inject]
protected ConfigInterface $config;

public function init() {
    $host = $this->config->get('databases.default.host');
}