# think-library **Repository Path**: topextend/think-library ## Basic Information - **Project Name**: think-library - **Description**: No description available - **Primary Language**: PHP - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2021-03-22 - **Last Updated**: 2025-05-21 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ThinkPHP 分层架构扩展库 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![PHP Version](https://img.shields.io/badge/php-%3E%3D8.0-brightgreen.svg)](https://php.net/) [![ThinkPHP Version](https://img.shields.io/badge/thinkphp-%3E%3D8.0-orange.svg)](https://www.thinkphp.cn/) 基于 ThinkPHP 8.x 的扩展库，提供了一套标准化的分层架构（Controller-Service-Repository-Model）、常用的 API 功能（JWT 认证、API 版本控制、速率限制）以及基础组件（统一异常处理、响应格式、辅助函数等）。 ## 📚 目录 - [安装与使用](#安装与使用) - [目录结构](#目录结构) - [核心功能](#核心功能) - [架构概述](#架构概述) - [分层设计](#分层设计) - [错误处理机制](#错误处理机制) - [响应格式规范](#响应格式规范) - [HTTP状态码管理](#http状态码管理) - [最佳实践](#最佳实践) - [开发规范](#开发规范) - [版权信息](#版权信息) ## 🚀 安装与使用 **1. 安装** 通过 Composer 安装本扩展库： ```bash composer require topextend/think-library ``` **2. 自动服务注册** 本扩展库的 `think\admin\Library` 服务会自动注册（依赖 `thinkphp/services`），无需手动配置。该服务会进行一些初始化工作，例如注册自定义的异常处理。 **3. 使用** * **继承基类**: * 让你的控制器继承 `think\admin\Controller` * 让你的服务类继承 `think\admin\Service` * 让你的仓库类继承 `think\admin\Repository` * 让你的模型类继承 `think\admin\Model` * 这将为你提供统一的响应方法、错误处理、事务支持、数据处理等基础能力。 * **使用 Traits**: * 按需在你的类中使用 `src/traits` 目录下的 Traits，例如： * `ResponseTrait`: 提供 `success()`, `error()`, `paginate()` 等响应方法。 * `ErrorCodeTrait`: 提供统一的错误码管理。 * `CacheTrait`: 提供基础的缓存读写封装。 * `HttpStatusTrait`: 提供 HTTP 状态码常量。 * `ListenerTrait`: 提供简单的事件监听/触发功能。 * **配置和使用中间件**: * 在 `app/middleware.php` 中按需注册和配置 `src/middleware` 下的中间件： * `LoadJwtAuth`: JWT 认证中间件。 * `LoadRateLimit`: 请求速率限制中间件。 * `CheckApiVersion`: API 版本检查中间件。 * `LoadMultiApp`: ThinkPHP 多应用支持中间件。 * 具体配置方法请参考 ThinkPHP 官方文档和各中间件的实现。 * **异常处理**: * 抛出 `src/exception` 目录下的自定义异常（`AuthException`, `BusinessException`, `DataException`），`ExceptionHandler` 会自动捕获并按规范格式响应。 * **服务调用**: * 可以直接通过依赖注入或 `app()` 助手函数获取并使用 `src/service` 目录下的服务，例如 `JwtService`, `ApiVersionService` 等。 * **辅助函数**: * `src/Helper.php` 中的函数会自动加载，可以直接调用。 ## 📁 目录结构 ``` . ├── LICENSE # 项目许可证 (MIT) ├── README.md # 项目说明文档 ├── composer.json # PHP 依赖管理文件 ├── src # 源代码目录 (命名空间 think\admin) │ ├── Controller.php # 控制器基类 │ ├── Exception.php # 异常基类 │ ├── Helper.php # 辅助函数 (全局加载) │ ├── Library.php # 核心库/服务注册类 │ ├── Model.php # 模型基类 │ ├── Repository.php # 仓库基类 │ ├── Service.php # 服务基类 │ ├── exception # 自定义异常类目录 │ │ ├── AuthException.php # 认证异常 │ │ ├── BusinessException.php # 业务逻辑异常 │ │ ├── DataException.php # 数据相关异常 │ │ └── ExceptionHandler.php # 统一异常处理器 │ ├── extend # 预留扩展目录 │ ├── lang # 语言包目录 │ │ └── zh-cn.php # 简体中文语言包 │ ├── middleware # 中间件目录 │ │ ├── CheckApiVersion.php # API 版本检查中间件 │ │ ├── LoadJwtAuth.php # JWT 认证加载中间件 │ │ ├── LoadMultiApp.php # 多应用加载中间件 │ │ └── LoadRateLimit.php # 请求速率限制中间件 │ ├── model # 模型目录 (示例或基础模型) │ │ ├── SystemApiGrayReleases.php # API 灰度发布模型 │ │ ├── SystemApiInterfaces.php # API 接口模型 │ │ ├── SystemApiVersions.php # API 版本模型 │ │ ├── SystemConfig.php # 系统配置模型 │ │ └── SystemConfigGroup.php # 系统配置分组模型 │ ├── repository # 仓库目录 (示例或基础仓库) │ │ ├── ApiVersionRepository.php # API 版本仓库 │ │ └── SystemRepository.php # 系统相关仓库 │ ├── service # 服务目录 │ │ ├── ApiVersionService.php # API 版本服务 │ │ ├── AuthService.php # 认证服务 │ │ ├── JwtService.php # JWT 服务 │ │ └── SystemService.php # 系统服务 │ └── traits # Traits 目录 │ ├── CacheTrait.php # 缓存相关 Trait │ ├── ErrorCodeTrait.php # 错误码相关 Trait │ ├── HttpStatusTrait.php # HTTP 状态码相关 Trait │ ├── ListenerTrait.php # 事件监听相关 Trait │ └── ResponseTrait.php # 响应处理相关 Trait └── test # 测试代码目录 ├── controller # 控制器测试 ├── exception # 异常测试 ├── model # 模型测试 ├── repository # 仓库测试 ├── service # 服务测试 └── validate # 验证器测试 ``` ## ✨ 核心功能 * **标准化分层架构**: 提供 `Controller`, `Service`, `Repository`, `Model` 基类，规范开发模式。 * **JWT (JSON Web Token) 认证**: 集成 JWT 服务 (`JwtService`) 和认证中间件 (`LoadJwtAuth`)，方便实现 API 认证。 * **API 版本控制与灰度发布**: 提供 API 版本检查中间件 (`CheckApiVersion`) 和相关服务/模型/仓库，支持 API 版本管理和灰度策略。 * **请求速率限制**: 通过 `LoadRateLimit` 中间件限制接口访问频率，防止恶意请求。 * **统一异常处理**: 定义了多种业务场景异常 (`AuthException`, `BusinessException`, `DataException`) 和统一的异常处理器 (`ExceptionHandler`)，规范错误响应。 * **标准化响应格式**: 通过 `ResponseTrait` 提供统一的 `success`, `error`, `paginate` 响应方法。 * **系统配置管理**: 提供基础的系统配置模型和服务 (`SystemConfig`, `SystemConfigGroup`, `SystemService`)。 * **辅助工具**: 包含常用 Traits (`CacheTrait`, `ErrorCodeTrait`, `HttpStatusTrait`等) 和全局辅助函数 (`Helper.php`)。 * **多应用支持**: `LoadMultiApp` 中间件用于支持 ThinkPHP 的多应用模式。 * **多语言支持**: 内置中文语言包 (`lang/zh-cn.php`)。 ## �� 架构概述 ### 分层结构 ``` Controller层 (控制器层) ↓ Service层 (服务层) ↓ Repository层 (仓储层) ↓ Model层 (模型层) ``` ### 核心特性 - 完整的分层架构设计 - 统一的错误处理机制 - 标准化的响应格式 - 灵活的服务编排能力 - 强大的数据处理能力 - 规范的开发模式约束 - 完善的异常处理体系 - 集成常用 API 功能 (JWT, 版本控制, 速率限制) ## 📋 分层设计 ### 控制器层 (Controller) 职责: - 处理 HTTP 请求和响应 - 参数验证和过滤 - 服务编排和协调 - 统一响应格式化 - 异常捕获和处理 特点: - 可以调用多个服务 - 不包含具体业务逻辑 - 统一的异常处理机制 - 标准的响应格式规范 ```php class Controller { protected Service $service; // 主服务 protected array $services = []; // 关联服务 // 统一响应方法 protected function success($data = null, string $message = 'success'): Response protected function error(string $message = '', int $code = 400): Response protected function paginate(array $items, int $total, int $page, int $limit): Response } ``` ### 服务层 (Service) 职责: - 业务逻辑处理 - 事务管理 - 多仓储协调 - 数据组装和转换 - 业务规则验证 特点: - 可以调用多个仓储 - 可以调用其他服务 - 包含核心业务逻辑 - 处理业务异常 - 支持事务操作 ```php class Service { protected Repository $repository; // 主仓储 protected array $repositories = []; // 关联仓储 protected array $services = []; // 关联服务 // 事务处理方法 protected function transaction(callable $callback) // 业务检查方法 protected function checkBusiness(array $data) } ``` ### 仓储层 (Repository) 职责: - 数据访问和处理 - 复杂查询封装 - 数据缓存处理 - 模型关联处理 - 数据持久化操作 特点: - 可以操作多个模型 - 处理数据访问逻辑 - 封装复杂查询 - 处理数据异常 - 支持缓存机制 ```php class Repository { protected Model $model; // 主模型 protected array $models = []; // 关联模型 // 数据处理方法 protected function prepareData(array $data): array // 缓存处理方法 protected function handleCache($data) } ``` ### 模型层 (Model) 职责: - 数据表映射 - 字段定义 - 基础CRUD操作 - 模型关联定义 - 数据验证规则 特点: - 不调用其他层 - 只负责数据结构 - 基础数据操作 - 定义数据关联 - 字段类型映射 ```php class Model { protected $table = 'table_name'; protected $schema = []; protected $relations = []; protected $rules = []; } ``` ## 📋 错误处理机制 ### 错误码体系 采用分层设计的错误码系统： ``` 0 - 成功 1-99 - 全局错误码 1000-1999 - 认证权限相关错误 2000-2999 - 业务逻辑相关错误 3000-3999 - 第三方服务相关错误 4000-4999 - 数据操作相关错误 5000-5999 - 系统级别错误 ``` ### 异常体系 框架提供的异常类： ```php Exception // 框架基础异常类 ├── AuthException // 认证相关异常 ├── BusinessException // 业务逻辑异常 ├── DataException // 数据操作异常 └── ValidateException // 数据验证异常 ``` ### 异常处理示例 ```php // 认证异常 throw new AuthException('未登录', AuthException::AUTH_ERROR); throw new AuthException('Token已过期', AuthException::TOKEN_EXPIRED); // 业务异常 throw new BusinessException('操作失败', BusinessException::BUSINESS_ERROR); throw new BusinessException('状态错误', BusinessException::STATUS_ERROR); // 数据异常 throw new DataException('数据不存在', DataException::DATA_NOT_FOUND); throw new DataException('数据已存在', DataException::DATA_ALREADY_EXIST); ``` ## 📋 响应格式规范 ### 成功响应 ```json { "code": 0, "message": "操作成功", "data": { // 响应数据 } } ``` ### 错误响应 ```json { "code": 1001, "message": "Token已过期", "data": null } ``` ### 分页响应 ```json { "code": 0, "message": "操作成功", "data": { "items": [], "total": 100, "page": 1, "limit": 15, "pages": 7 } } ``` ## 📋 HTTP状态码管理 框架统一定义了常用的HTTP状态码： ### 2xx 成功响应 - 200 OK：请求成功 - 201 Created：创建成功 - 204 No Content：删除成功 ### 4xx 客户端错误 - 400 Bad Request：请求参数错误 - 401 Unauthorized：未授权 - 403 Forbidden：禁止访问 - 404 Not Found：资源不存在 - 422 Unprocessable Entity：数据验证失败 ### 5xx 服务器错误 - 500 Internal Server Error：服务器内部错误 - 503 Service Unavailable：服务不可用 ## 📋 最佳实践 ### 控制器层最佳实践 ```php class UserController extends Controller { public function index() { return $this->catchException(function() { // 1. 获取请求数据 $data = $this->request->post(); // 2. 验证数据 $this->validate($data, 'User.create'); // 3. 调用服务 $result = $this->service->createUser($data); // 4. 返回响应 return $this->success($result); }); } } ``` ### 服务层最佳实践 ```php class UserService extends Service { public function createUser(array $data) { return $this->transaction(function() use ($data) { // 1. 业务检查 $this->checkUserData($data); // 2. 创建用户 $user = $this->repository->create($data); // 3. 处理关联数据 $this->handleUserRelations($user); return $user; }); } } ``` ### 仓储层最佳实践 ```php class UserRepository extends Repository { public function create(array $data) { return $this->catchDbException(function() use ($data) { // 1. 准备数据 $userData = $this->prepareUserData($data); // 2. 创建记录 $user = $this->model->create($userData); // 3. 更新缓存 $this->updateUserCache($user); return $user; }); } } ``` ## 📋 开发规范 ### 命名规范 - 控制器：UserController - 服务：UserService - 仓储：UserRepository - 模型：UserModel ### 目录结构 ``` app/ ├── controller/ # 控制器目录 ├── service/ # 服务目录 ├── repository/ # 仓储目录 ├── model/ # 模型目录 └── validate/ # 验证器目录 ``` ### 代码规范 - 遵循PSR-4自动加载规范 - 遵循PSR-12代码风格规范 - 使用强类型声明 - 编写完整的方法注释 - 合理使用设计模式 ## 📄 版权信息 ThinkPHP think-library 遵循 MIT 开源协议发布，并提供免费使用。 - 作者：Jarmin - 邮箱：jarmin@ladmin.cn - 网站：http://www.ladmin.cn