---1)目标定义开源仓库定位 仓库名建议hyperf-starter-kit 定位开箱即用的 Hyperf API 服务脚手架内置 - 健康检查 - 统一响应结构 - 依赖注入分层Controller / Service / Repository - MySQL Redis - 迁移 - 单元测试 - 静态检查 - GitHub Actions CI - Docker 化开发 ---2)从0初始化项目composercreate-project hyperf/hyperf-skeleton hyperf-starter-kitcdhyperf-starter-kit# 常用组件composerrequire hyperf/db-connection hyperf/database hyperf/rediscomposerrequire hyperf/validation hyperf/swaggercomposerrequire--devphpunit/phpunit friendsofphp/php-cs-fixer phpstan/phpstan ---3)推荐目录结构 hyperf-starter-kit/ ├─ app/ │ ├─ Controller/V1/ │ ├─ Service/ │ ├─ Repository/ │ │ └─ Contract/ │ ├─ Model/ │ └─ Exception/Handler/ ├─ config/autoload/ ├─ migrations/ ├─ tests/ ├─ .github/workflows/ ├─ Dockerfile ├─ docker-compose.yml ├─ Makefile ├─ README.md ├─ CONTRIBUTING.md ├─ CODE_OF_CONDUCT.md ├─ SECURITY.md └─ CHANGELOG.md ---4)核心代码可直接用4.1统一 API 响应助手 app/Support/ApiResponse.php?php declare(strict_types1);namespace App\Support;class ApiResponse{public staticfunctionsuccess(mixed$datanull, string$messageok): array{return[code0,message$message,data$data,tstime(),];}public staticfunctionerror(int$code, string$message, mixed$datanull): array{return[code$code,message$message,data$data,tstime(),];}}4.2健康检查接口 app/Controller/V1/HealthController.php?php declare(strict_types1);namespace App\Controller\V1;use App\Support\ApiResponse;use Hyperf\HttpServer\Annotation\Controller;use Hyperf\HttpServer\Annotation\GetMapping;#[Controller(prefix: /api/v1/health)]class HealthController{#[GetMapping(path: )]publicfunctionindex(): array{returnApiResponse::success([servicehyperf-starter-kit,statusup,]);}}4.3User 示例Controller / Service / Repository app/Repository/Contract/UserRepositoryInterface.php?php declare(strict_types1);namespace App\Repository\Contract;interface UserRepositoryInterface{publicfunctionfindById(int$id): ?array;}app/Repository/UserRepository.php?php declare(strict_types1);namespace App\Repository;use App\Model\User;use App\Repository\Contract\UserRepositoryInterface;class UserRepository implements UserRepositoryInterface{publicfunctionfindById(int$id): ?array{$userUser::query()-find($id);return$user?-toArray();}}app/Service/UserService.php?php declare(strict_types1);namespace App\Service;use App\Repository\Contract\UserRepositoryInterface;class UserService{publicfunction__construct(privatereadonlyUserRepositoryInterface$userRepository){}publicfunctiongetUserProfile(int$id): ?array{return$this-userRepository-findById($id);}}app/Controller/V1/UserController.php?php declare(strict_types1);namespace App\Controller\V1;use App\Service\UserService;use App\Support\ApiResponse;use Hyperf\Di\Annotation\Inject;use Hyperf\HttpServer\Annotation\Controller;use Hyperf\HttpServer\Annotation\GetMapping;#[Controller(prefix: /api/v1/users)]class UserController{#[Inject]protected UserService$userService;#[GetMapping(path: {id:\d})]publicfunctionshow(int$id): array{$user$this-userService-getUserProfile($id);if(!$user){returnApiResponse::error(40401,user not found);}returnApiResponse::success($user);}}4.4依赖绑定 config/autoload/dependencies.php?php declare(strict_types1);use App\Repository\Contract\UserRepositoryInterface;use App\Repository\UserRepository;return[UserRepositoryInterface::classUserRepository::class,];4.5Model Migration app/Model/User.php?php declare(strict_types1);namespace App\Model;use Hyperf\DbConnection\Model\Model;class User extends Model{protected ?string$tableusers;protected array$fillable[name,email,];}migrations/2026_04_25_000001_create_users_table.php?php declare(strict_types1);use Hyperf\Database\Migrations\Migration;use Hyperf\Database\Schema\Blueprint;use Hyperf\Database\Schema\Schema;returnnew class extends Migration{publicfunctionup(): void{Schema::create(users,function(Blueprint$table){$table-bigIncrements(id);$table-string(name,64);$table-string(email,128)-unique();$table-timestamps();});}publicfunctiondown(): void{Schema::dropIfExists(users);}};---5)开发环境Docker docker-compose.yml version:3.9services: app: image: php:8.2-cli working_dir: /app volumes: - ./:/app command:bash-lcphp -v php bin/hyperf.php startports: -9501:9501depends_on: - mysql - redis mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: root MYSQL_DATABASE: hyperf_starter MYSQL_USER: hyperf MYSQL_PASSWORD: hyperf ports: -3306:3306redis: image: redis:7-alpine ports: -6379:6379---6)质量门禁本地命令 Makefile .PHONY: cs-fix cs-checkteststatic qa cs-fix: vendor/bin/php-cs-fixer fix cs-check: vendor/bin/php-cs-fixer fix --dry-run--difftest: vendor/bin/phpunit static: vendor/bin/phpstan analyse app tests--levelmax qa: cs-check statictest---7)CIGitHub Actions .github/workflows/ci.yml name: CI on: pull_request: push: branches:[main]jobs: qa: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 - name: Setup PHP - uses: shivammathur/setup-phpv2 with: php-version:8.2extensions: mbstring, pdo_mysql, redis coverage: none - name: Install deps run:composerinstall--no-interaction --prefer-dist - name: CS check run:makecs-check - name: Static analysis run:makestatic - name: Tests run:maketest▎ 注意上面 Setup PHP 那段要修正缩进- uses 与 name 对齐我这里给你的是内容模板复制时按 YAML 标准缩进即可。 ---8)开源仓库必备文档 至少补齐这些文件 - README.md安装、运行、接口示例、架构图 - CONTRIBUTING.md分支规范、提交规范、PR 流程 - SECURITY.md漏洞提交流程邮箱 / 私密渠道 - CODE_OF_CONDUCT.md社区行为准则 - CHANGELOG.md版本变更记录Keep a Changelog ---9)发布策略建议 - 分支main稳定feat/*功能fix/*修复 - 版本SemVerv1.2.3 - 提交规范Conventional Commitsfeat:, fix:, chore: - 发布节奏双周小版本季度大版本 - 每次发布包含 a. CHANGELOG 更新 b. Git tag c. GitHub Release 说明 d. 升级指南破坏性变更必须写 ---10)持续维护 SOP操作日志 你说要“完整操作日志”这里给你可直接用的模板 OPEN_SOURCE_OPS_LOG.md# Open Source Ops Log## 2026-04-25- Action: 初始化仓库与基础目录 - Detail: 完成 Hyperf skeleton、README、License、CI 初版 - Result: v0.1.0-dev 可运行 - Risk: 无迁移回滚方案 - Next: 增加 migration rollback 文档## 2026-04-26- Action: 增加 User 示例模块 - Detail: Controller/Service/Repository 分层 usersmigration - Result: /api/v1/users/{id}可用 - Risk: 缺少鉴权 - Next: 接入 JWT 中间件并补测试## 2026-04-27- Action: 建立 QA 门禁 - Detail: php-cs-fixer phpstan phpunit GitHub Actions - Result: PR 自动阻断不合规提交 - Risk: 覆盖率不足 - Next: 核心service覆盖率提升到80% ---11)最小上线命令清单团队交接最有用# 本地开发composerinstallphp bin/hyperf.php migrate php bin/hyperf.php start# 质量检查makeqa# 打标签发布gittag v0.1.0gitpush origin v0.1.0 ---12)一句话落地建议 先按上面代码做出 v0.1.0保证“能跑 有测试 有 CI 有文档”再迭代鉴权、日志、追踪、限流。开源项目早期最关键的是稳定维护节奏不是一次堆满功能。