README

下一代 ThinkPHP 脚手架工具：代码生成器 + 基类控制器 + 公共服务库

简介

TpInit 是一个为 ThinkPHP 8.x 设计的全功能脚手架工具，整合了：

📊 Excel 驱动的代码生成器：从 Excel 生成 Model、Migration、SQL、Controller、Service、Validate
🎯 现代化基类控制器：内置用户注入、布局模板、统一响应格式
🛠️ 实用服务层：图片处理、分页、URL 生成、七牛云、加密等

核心特性

✅ 代码生成

从 Excel 定义表结构，一键生成全套代码
支持字段类型、索引、关联关系、验证规则
新增：支持生成 Service 业务逻辑层和 Validate 验证器
新增：交互式命令行向导，无需记忆复杂参数
自定义代码保护区，重新生成不覆盖业务代码
支持软删除、时间戳、多态关联

✅ 基类控制器

BaseWebController：布局模板、用户自动注入、全局变量
BaseApiController：统一 JSON 响应、跨域支持、参数验证
success()/fail() 快速响应

✅ 服务层

ImageService：图片 CDN、尺寸裁剪（七牛云）
PaginationService：统一分页查询
UrlService：详情页、栏目页 URL 生成
QiniuService：七牛云上传、Token 生成
CryptoService：SHA1、密码哈希、加密解密
UploadService：本地文件上传

目录结构

src/
├── Command/        # 命令行工具 (Generate, Install, ExcelDemo)
├── Config/         # 默认配置文件
├── Controller/     # 基类控制器 (BaseApiController, BaseWebController)
├── Generator/      # 代码生成器逻辑
├── Helpers/        # 辅助函数
├── Parser/         # Excel 解析器
├── Schema/         # 数据库结构定义
├── Service/        # 公共服务库
│   ├── CryptoService.php       # 加密服务
│   ├── ExcelService.php        # Excel 导入导出
│   ├── HttpService.php         # HTTP 客户端
│   ├── ImageService.php        # 图片处理
│   ├── PaginationService.php   # 分页服务
│   ├── QiniuService.php        # 七牛云服务
│   ├── RedisService.php        # Redis 工具
│   ├── TreeService.php         # 树形结构处理 (O(n) 高性能)
│   ├── UploadService.php       # 本地上传
│   └── UrlService.php          # URL 生成
├── Support/        # 内部支持类
├── Traits/         # 通用 Traits

详细的使用文档请参考 USAGE.md。

安装

环境要求

PHP >= 8.1
ThinkPHP >= 8.0
Composer

使用 Composer 安装

composer require 10soo/tpinit

安装配置文件

php think tpinit:install

这将：

复制配置文件到 config/tpinit.php
创建必要的目录（think/、database/migrations/）

快速开始

1. 生成示例 Excel

php think tpinit:excel-demo

这将在 database/db.xlsx 生成一个包含示例表结构的 Excel 文件。

2. 编辑 Excel 定义表结构

打开 database/db.xlsx，按照以下格式定义表结构：

表名	表注释	字段名	类型	可空	注释	索引	关联	验证
user	用户表	username	varchar(50)		用户名	unique		required\|max:50
		email	varchar(100)	Y	邮箱	index		email
		password	varchar(255)		密码			required
article	文章表	title	varchar(200)		标题			required
		content	text		内容
		user_id	bigint		作者 ID	index	@user

关联语法：

@表名：一对一（hasOne）
@表名@：一对多（hasMany）
&表名：多态一对一（morphOne）
&表名&：多态一对多（morphMany）

3. 生成代码

# 交互式向导（推荐）
php think tpinit:generate

# 生成所有（Model + Migration + SQL + Controller + Service + Validate）
php think tpinit:generate

# 仅生成指定类型
php think tpinit:generate --only=model,service,validate

# 仅生成 Controller（API 风格）
php think tpinit:generate --only=controller --preset=api

# Dry Run 模式（预览不写文件）
php think tpinit:generate --dry-run

# 强制覆盖已存在文件
php think tpinit:generate --force

4. 运行迁移

# 初始化迁移表
php think migrate:run

使用指南

基类控制器

Web 控制器

<?php

namespace app\controller;

use TpInit\Controller\BaseWebController;
use app\model\User;

class IndexController extends BaseWebController
{
    protected string $layout = '_web'; // 布局模板

    protected function initialize(): void
    {
        parent::initialize();

        // $this->user 已自动注入当前登录用户
        // $this->reqId 已自动从 GET/POST 获取 id
    }

    public function index()
    {
        // 全局变量会自动传递给视图
        $this->globals['title'] = '首页';
        $this->globals['users'] = User::select();

        // 自动套用 layout 模板
        return $this->view();
    }

    public function save()
    {
        $user = User::create($this->request->post());

        if ($user) {
            return $this->success('创建成功', $user);
        }

        return $this->fail('创建失败');
    }
}

API 控制器

<?php

namespace app\controller\api;

use TpInit\Controller\BaseApiController;
use app\model\User;

class UserController extends BaseApiController
{
    protected bool $enableCors = true; // 启用跨域

    public function index()
    {
        $list = User::where('status', 1)
            ->order('id', 'desc')
            ->paginate(15);

        // 返回带分页信息的标准格式
        return $this->paginate($list);
    }

    public function save()
    {
        // 参数验证
        $data = $this->validate([
            'username' => 'require|max:50',
            'email' => 'require|email',
            'password' => 'require|min:6',
        ]);

        $user = User::create($data);
        return $this->success('创建成功', $user);
    }
}

服务层

图片服务

use TpInit\Service\ImageService;

$imageService = new ImageService();

// 获取图片 URL
$url = $imageService->url('uploads/avatar.jpg');

// 获取指定尺寸
$thumbnail = $imageService->url('uploads/avatar.jpg', '200x200');

// 或使用辅助函数（兼容旧写法）
$url = image('uploads/avatar.jpg', '300x300');

分页服务

use TpInit\Service\PaginationService;
use app\model\Article;

$paginationService = new PaginationService();

// 通用分页
$list = $paginationService->paginate(
    Article::class,
    ['status' => 1],
    ['id' => 'desc'],
    15
);

// 或使用辅助函数
$list = pageList(Article::class, ['status' => 1], 'id desc', 15);

URL 服务

use TpInit\Service\UrlService;

$urlService = new UrlService();

// 详情页 URL
$url = $urlService->show(['id' => 1, 'cate_id' => 5]);

// 栏目 URL
$cateUrl = $urlService->category(5);

// 或使用辅助函数
$url = show(['id' => 1]);
$cateUrl = cateUrl(5);

加密服务

use TpInit\Service\CryptoService;

$cryptoService = new CryptoService();

// SHA1 加密
$hash = $cryptoService->sha1('password');

// 密码哈希
$hash = $cryptoService->passwordHash('password');

// 验证密码
$valid = $cryptoService->passwordVerify('password', $hash);

// 生成随机字符串
$random = $cryptoService->random(32);

辅助函数

// 图片处理
$url = image('uploads/avatar.jpg', '300x200');

// 分页查询
$list = pageList(Article::class, ['status' => 1], 'id desc', 15);

// 详情页 URL
$url = show(['id' => 1]);

// 栏目 URL
$url = cateUrl(5);

// 检测微信客户端
if (isWx()) {
    // 微信内浏览器
}

// SHA1 加密
$hash = sha1Encrypt('password');

// 获取服务实例
$imageService = tpinit_service('ImageService');

// 获取配置
$cdnDomain = tpinit_config('image.cdn_domain');

配置

编辑 config/tpinit.php：

return [
    // Excel 配置
    'excel' => [
        'path' => 'think/db.xlsx',
        'sheet_name' => 'Sheet1',
        'start_row' => 2,
    ],

    // 生成配置
    'generate' => [
        'model_path' => 'app/model',
        'controller_path' => 'app/controller',
        'migration_path' => 'database/migrations',
        'sql_path' => 'database',
        'force_overwrite' => false,
        'backup_old_files' => true,
    ],

    // 控制器配置
    'controller' => [
        'layout' => '_web',
        'session_user_key' => 'user',
        'auto_assign_user' => true,
        'response_format' => [
            'success_code' => 1,
            'fail_code' => 0,
        ],
    ],

    // 图片服务配置
    'image' => [
        'driver' => 'qiniu',
        'cdn_domain' => 'https://cdn.example.com',
    ],

    // 七牛云配置
    'qiniu' => [
        'access_key' => '',
        'secret_key' => '',
        'bucket' => '',
        'domain' => '',
    ],
];

命令行工具

tpinit:install

安装配置文件和目录

php think tpinit:install

tpinit:excel-demo

生成示例 Excel 文件

php think tpinit:excel-demo

tpinit:generate

从 Excel 生成代码

# 交互式模式（推荐）
php think tpinit:generate

# 生成所有
php think tpinit:generate

# 指定 Excel 文件
php think tpinit:generate --excel=database/tables.xlsx

# 仅生成指定类型
php think tpinit:generate --only=model,service,validate

# Dry Run 模式
php think tpinit:generate --dry-run

# 强制覆盖
php think tpinit:generate --force

选项：

--excel：Excel 文件路径（默认：think/db.xlsx）
--only：仅生成指定类型（model|migration|sql|controller|service|validate）
--dry-run：Dry Run 模式（只预览不写文件）
--force：强制覆盖已存在文件
--preset：预设模板（default|api|web，用于 Controller）

高级用法

自定义代码保护

生成的 Model 和 Controller 包含自定义代码保护区：

<?php

namespace app\model;

use think\Model;

class User extends Model
{
    // ... 自动生成的代码 ...

    // ---------- Custom code below ----------

    // 这里的代码重新生成时不会被覆盖
    public function getStatusTextAttr()
    {
        return $this->status ? '正常' : '禁用';
    }
}

扩展生成器

创建自定义生成器：

<?php

namespace app\generator;

use TpInit\Generator\AbstractGenerator;
use TpInit\Schema\Table;

class MyGenerator extends AbstractGenerator
{
    protected function generateCode(Table $table): string
    {
        // 生成自定义代码
        return "// Custom code for {$table->name}";
    }

    protected function getOutputPath(Table $table): string
    {
        return "output/{$table->name}.php";
    }
}

自定义服务

创建自定义服务：

<?php

namespace app\service;

class MyService
{
    public function doSomething()
    {
        // 业务逻辑
    }
}

// 使用
$service = tpinit_service('MyService');

常见问题

Q: 生成的代码中文乱码？

A: 确保 Excel 文件使用 UTF-8 编码保存。

Q: 重新生成会覆盖我的代码吗？

A: 不会。自定义代码保护区（// ---------- Custom code below ---------- 下方）的代码不会被覆盖。

Q: 如何使用多态关联？

A: 在 Excel 中使用 &表名& 语法，多态表必须包含 xxx_type 和 xxx_id 字段。

Q: 支持 ThinkPHP 6 吗？

A: 主要针对 ThinkPHP 8.x，ThinkPHP 6 未充分测试但理论上兼容。

Q: 如何自定义响应格式？

A: 编辑 config/tpinit.php 的 controller.response_format 配置。

贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork 本仓库
创建特性分支：git checkout -b feature/your-feature
提交更改：git commit -m 'Add some feature'
推送分支：git push origin feature/your-feature
提交 Pull Request

开源协议

MIT License

致谢

ThinkPHP - 优秀的 PHP 框架
PhpSpreadsheet - Excel 处理库
社区贡献者们

享受编码！ 🚀

10soo / tpinit

Maintainers

Details