README

ThinkPHP 8 通用后台开发类库：分层脚手架 + 基础设施。

本库只提供可复用的开发约定与工具（控制器基类、Application/Repository 抽象、JWT、中间件、存储、操作日志等），不包含具体业务表、租户、插件、菜单种子等平台/SaaS 逻辑。业务实现请参考上层应用 cloud/apps/admin-api（app/platform 通用后台 + app/cloud SaaS 扩展）。

要求

PHP >= 8.1
ThinkPHP ^8.0
think-orm ^3.0|^4.0

安装

composer require topextend/think-library

ThinkPHP 项目需在 composer.json 中启用服务发现（默认已开启），库会自动注册 think\library\bootstrap\Library 服务。

本地 monorepo 开发可在应用 composer.json 中配置 path 仓库指向 packages/think-library。

目录结构

src/
├── bootstrap/              # Library 服务注册、Runtime
├── common.php              # syspath()、sysvar() 全局助手
├── foundation/
│   ├── ApiController.php   # JSON API 控制器基类
│   ├── BaseService.php     # 单例服务基类
│   └── BaseApplication.php # 用例层基类
├── domain/
│   ├── contract/           # RepositoryInterface、OplogWriterInterface
│   ├── oplog/              # OplogEntry
│   ├── result/             # PageResult
│   ├── storage/            # Storage 文件引擎
│   ├── PluginRegistry.php  # 多应用/插件注册表
│   └── AppNamespace.php
├── application/
│   ├── RbacMatcher.php     # RBAC 路径/菜单匹配（纯逻辑）
│   └── CronMatcher.php     # Cron 表达式匹配
└── infrastructure/
    ├── persistence/        # AbstractRepository
    ├── storage/            # LocalPublicStorage 等驱动
    ├── middleware/         # 见下文「中间件」
    ├── oplog/              # OplogWriter、ApiOplogRecorder
    ├── Jwt.php
    ├── Validate.php
    ├── Tools.php
    └── DatabaseSupport.php

分层约定

推荐调用链：

Controller → Application (*Manage) → Repository → Db

层级	库内基类	职责
Controller	`ApiController`	HTTP 入参/出参、`success`/`error`、参数校验
Application	`BaseApplication`	编排用例，调用 Repository，不写 SQL
Repository	`AbstractRepository`	表访问、分页、CRUD 封装

控制器示例

namespace app\demo\controller;

use think\library\foundation\ApiController;
use app\demo\application\ArticleManage;

class Article extends ApiController
{
    public function list()
    {
        $page = max(1, (int) $this->request->get('page', 1));
        $pageSize = max(1, min(100, (int) $this->request->get('pageSize', 20)));
        $this->success('ok', ArticleManage::instance()->list($page, $pageSize));
    }

    public function save()
    {
        $data = $this->_vali(['title.require' => '标题不能为空']);
        ArticleManage::instance()->save($data);
        $this->writeOplog('文章管理', '保存', $data['title'] ?? '');
        $this->success('保存成功');
    }
}

Application 示例

namespace app\demo\application;

use think\library\foundation\BaseApplication;
use app\demo\persistence\ArticleRepository;

class ArticleManage extends BaseApplication
{
    public function list(int $page, int $limit): array
    {
        $result = ArticleRepository::instance()->paginate($page, $limit);
        return $result->toArray();
    }
}

Repository 示例

namespace app\demo\persistence;

use think\library\infrastructure\persistence\AbstractRepository;

class ArticleRepository extends AbstractRepository
{
    protected function table(): string
    {
        return 'article';
    }

    protected function query()
    {
        return \think\facade\Db::name($this->table())->where('is_deleted', 0);
    }
}

AbstractRepository 已内置 instance() 单例，子类可直接 ArticleRepository::instance()。

自动注册的服务

Library 服务在 register() 阶段会：

加载应用目录下的 sys.php、common.php、provider.php、event.php、middleware.php（可选）
注册全局 CORS 中间件
注册 LoadLangPack、JwtAccess、RbacAccess、LangPackAccess、ApiOplogAccess

JWT / RBAC / Oplog 中间件会按 config/library.php 中各节的 scopes.{name}.scope_matcher 自动匹配命名 scope，无需在应用里写包装类或 app/{app}/middleware.php。

在 boot() 阶段的 HttpRun 事件中注册 MultAccess（多应用调度）。

中间件

中间件	说明
`MultAccess`	多应用 URL 解析与 `app/{name}/` 加载
`JwtAccess`	JWT 鉴权（按 `jwt.scopes` 自动匹配）
`RbacAccess`	RBAC 权限校验（需在 Jwt 之后）
`LangPackAccess`	语言包加载（通过配置注入）
`ApiOplogAccess`	API 访问自动记操作日志（支持命名 scope）
`AppRequestUtil`	多应用 path 识别与归一化工具类

库内中间件不包含租户解析等业务逻辑；业务侧在应用 config/library.php 中通过回调注入规则。

config/library.php 示例

在业务项目（如 admin-api）创建 config/library.php：

<?php

use think\Request;

return [
    // JWT（租户 API 默认 scope）
    'jwt' => [
        'ignore' => ['auth/login', 'login/index'],
        'scope_matcher' => fn (Request $r) => str_starts_with($r->pathinfo(), 'api'),
        'secret' => fn () => (string) config('jwt.secret'),
        'user_resolver' => function (array $payload, Request $r) {
            // 返回用户数组或 null
        },
        // 命名 scope：平台后台
        'scopes' => [
            'admin' => [
                'scope_matcher' => fn (Request $r) => app()->http->getName() === 'platform',
                'path_normalizer' => fn (Request $r) => trim($r->pathinfo(), '/'),
                'secret' => fn () => 'your-platform-secret',
                'user_resolver' => fn (array $payload) => /* ... */,
                'user_alias' => 'adminUser',
            ],
        ],
    ],

    // RBAC
    'rbac' => [
        'guard' => \app\cloud\application\RbacGuard::class,
        'scope_id' => fn () => tenant()->id(),
        'scopes' => [
            'admin' => [
                'checker' => fn (int $uid, string $method, string $path) => true,
            ],
        ],
    ],

    // 语言包
    'lang_pack' => [
        'register' => fn (Request $r) => /* 加载语言包 */,
    ],

    // 操作日志
    'oplog' => [
        'default_scope' => 'tenant',
        'writers' => [
            'platform' => \app\\admin\infrastructure\AdminOplogWriter::class,
            'tenant' => \app\cloud\infrastructure\TenantOplogWriter::class,
        ],
        'scopes' => [
            'admin' => [
                'writer_scope' => 'admin',
                'node_map' => ['admin/' => '用户管理'],
            ],
        ],
    ],
];

操作日志 OplogWriter

use think\library\infrastructure\oplog\OplogWriter;

// 直接写入
OplogWriter::write('用户管理', '保存', '新增 admin', 'admin', 'platform');

// 控制器内（ApiController 已提供）
$this->writeOplog('用户管理', '保存', '新增 admin', null, 'platform');

实现 OplogWriterInterface 并在 config/library.php 的 oplog.writers 中注册即可接入自定义存储。

多应用与插件

继承 think\library\domain\PluginRegistry 注册子应用：

namespace app\mall;

class Service extends \think\library\domain\PluginRegistry
{
    protected string $appName = '商城';
    protected string $package = 'topextend/plugin-mall';
}

在应用 app/service.php 中注册该 Service，MultAccess 即可按 URL 前缀调度到 app/mall/。

可选配置覆盖：

'addon_registry' => \think\library\domain\PluginRegistry::class,

其他工具

组件	用途
`Jwt`	JWT 签发与校验，支持传入 secret
`Validate`	链式参数校验，供 `_vali()` 使用
`Storage`	文件存储门面（local/public，可扩展 OSS 等）
`PageResult`	分页结果 DTO
`RbacMatcher`	路径/菜单节点匹配，供业务 Guard 复用
`CronMatcher`	判断 cron 表达式是否到期
`DatabaseSupport`	建库/迁移脚本辅助
`syspath()` / `sysvar()`	项目路径与请求级变量

与 admin-api 的关系

包	职责
think-library	分层脚手架、JWT/中间件、存储、操作日志、多应用调度
admin-api	基于本库实现的通用后台与 Cloud SaaS（用户/角色/菜单/租户/插件等）

数据库脚本位于 monorepo 的 cloud/database/（全量）与 cloud/database/admin/（仅 platform 表）。

许可证

MIT

topextend/think-library

包简介

README 文档