# think-library

**Repository Path**: topextend/think-library

## Basic Information

- **Project Name**: think-library
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# think-library

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

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

## 要求

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

## 安装

```bash
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 封装 |

### 控制器示例

```php
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 示例

```php
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 示例

```php
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()` 阶段会：

1. 加载应用目录下的 `sys.php`、`common.php`、`provider.php`、`event.php`、`middleware.php`（可选）
2. 注册全局 CORS 中间件
3. 注册 `LangPackAccess`、`LoadLangPack`、`lang_pack.after_load` 钩子、`JwtAccess`、`RbacAccess`、`ApiOplogAccess`（先 boot 插件合并开放 API ignore / extend_list；LoadLangPack 后再强制重载语言，插件语言文件按 allow_group 写成 `['code'=>[...]]`）

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
<?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

```php
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` 注册子应用：

```php
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/`。

可选配置覆盖：

```php
'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/`：`mysql/install.sql` 与 `pgsql/install.sql`（根目录同名文件为兼容副本）。

## 许可证

MIT