Laravel 项目全自动接口管理 - 正式版 1.0 发布

什么是 StubApi#

StubApi 旨在为 Laravel 项目及其客户端提供一个功能强大、便捷、无侵入、可插拔的接口管理工具。

注：该工具推荐中高级 Laravel 开发者引入，因为要熟悉 Laravel 项目结构和原理。实际使用不需要掌握java，因为接口描述参照已有的写就可以了。

功能强大#

在 StubApi 中，有五种核心的数据元素：接口、传输数据模型（DTO）、标量数据、枚举、异常码。基于这些数据元素，实现了接口数据类型规范、接口版本控制、全局枚举值等功能。

便捷、无侵入#

与传统的接口管理工具不同，StubApi 不要求用户在模型中写繁琐的校验规则，也不要求用户为了数据响应建各种资源类，更不会用 service provider 或 middleware 污染其他接口。

接口所有的功能，都可以通过一小段声明式的代码达到目的。

可插拔#

即便有一天你不需要 StubApi，只需要保留三四个必要的基类文件，移除整个包都可以！

新版特色#

不再依赖 javadoc，支持 jdk8-12#

在预览版中，为了从接口模板同步注释到代码和文档中，使用了 javadoc。而从 jdk9 开始 javadoc 做了一个大重构，为了避免限制用户 jdk 版本，我改回使用 javaparser（仅对于注释），因而不再需要手动设置 JAVA_HOME 环境变量。

service 层改为成员方法#

在 controller -> service 的调用中，原本是调用 service 中的静态方法，改为调用成员函数，service 支持构造函数依赖注入（考虑过成员方法也支持依赖注入，但觉得不太常用，所以没有去支持）。

丰富了配置项#

现在包括生成代码的基类等都可以自定义并更换。

场景举例：希望更改响应格式规则，可以自定义 Message 基类，生成的代码将会使用你添加的基类。

完善了模板继承规则#

现在 DTO 可以相互继承，模板表达力更强。继承只为表达数据结构的关系和特点，所以生成后的代码只会继承结构，而不保留继承关系。

支持了 message getter 的类型提示#

在 service 层获取请求参数会有类型提示

    /**
     * 页面路径
     * @return string
     */
    public function getPath()
    {
        return $this->path;
    }
Copy

支持自定义数据类型#

可以自由添加需要的参数规则，如 Y-m 格式的时间，或对 mime 有特殊要求的文件。这些校验规则与自定义的 laravel validator 兼容。

支持通过模板方式生成代码（暂未开放）#

旧版本都是通过 Writter 方式，用 java 拼字符串并导出成文件的方式生成代码，未来会改为都用模板生成，用户可以自定义（模板引擎为 thymeleaf）。

接口响应流程#

一个成功响应的生命周期#

    // 从请求中封装Message
    public function feedback(FeedbackMessage $message)
    {
        // 验证请求数据
        $message->validateInput();
        // 调用用户逻辑层
        $this->handler->feedback($message);
        // 验证用户设置的响应是否符合接口规则
        $message->validateOutput();
        // 返回响应
        return $message->getResponse();
    }
Copy

用户逻辑实现#

    /**
     * @param PublishesMessage $message
     * @throws CustomErrorMessageException
     */
    public function publishes(PublishesMessage $message)
    {
        // 获取请求参数
        $page = $message->getPage();
        $type = $message->getType();
        $city = $message->getCity();
        $serviceTypes = $message->getServiceTypes();
        $workerTypes = $message->getWorkerTypes();

        $user = Auth::user();

        // 一些逻辑相关的校验，如订单未结束不能发起退款，可以直接用一个异常响应结束请求
        if (!$user) {
            throw new CustomErrorMessageException('用户不存在时的异常');
        }

        // 注入一个逻辑Manager，这样多版本service将会重复更少的代码
        $publishes = $this->publishManager->getPublishes(
            $user,
            $city,
            $type,
            $workerTypes,
            $serviceTypes,
            $page
        );

        // 设置响应，请求结束
        $message->setResponse(PublishModel::initFromEloquents($publishes));
    }
Copy

正式版使用方式#

安装#

引入

composer require kamicloud/stub-apiCopy

安装 jdk （可用 oracle jdk 代替）
brew tap adoptopenjdk/openjdk
brew cask install adoptopenjdk8

使用#

php artisan stub-api:installCopy

此时会在根目录创建一个 bin 文件

cd bin
./initGeneratorCopy

使用 jdk 编译工具

./generateCopy

当工具编译完成后，编译自己的模板并生成代码

配置#

路由（假设直接使用 Laravel 下的 api 路由）
这里的目的是把路由指向自动生成的控制器

app/Providers/RouteServiceProvider.php

    protected function mapApiRoutes()
    {
        Route::prefix('api')
            ->middleware('api')
            ->namespace('App\Generated\Controllers')
            ->group(base_path('routes/api.php'));
    }Copy

引入路由文件
routes/api.php

include_once 'generated_routes.php';Copy

在对应的路由规则中加入一个工具中间件

\Kamicloud\StubApi\Http\Middleware\GeneratorMiddleware

他只在你 env 为 testing 时或开启 debug 才有用，所以也可以不引入这个中间件。功能如传__test_mode 会自动回滚数据库，具体请看实现代码。

更换异常处理基类，或者参考工具提供的基类自己实现

Kamicloud\StubApi\Exceptions\Handler

写代码#

模板默认在 resources/generator/templates 下

参考旧模板使用教程

博客：Laravel 项目全自动接口管理（接口部分）

一些注意事项#

枚举值的 getter#

由于枚举值可以用 @StringEnum 传输字符串枚举，所以 getter 的返回值可能是 integer 也可能是 string，不太好修就暂时标记返回为 mixed。

时间传输格式和对应的 getter#

工具提供了两个配置项，getter 返回值也是 mixed

    /**
     * 默认时间的传输格式为字符串
     *
     * 开启后传输格式为整型
     */
    'request-date-timestamp' => false,
    'response-date-timestamp' => false,
Copy

建议引入工具时按需引入，指定版本号#

版本更新兼容性说明#

由于发布正式版，未来在小版本更新时如 1.0.10 到 1.0.11，除为修复 bug，将兼容旧版本模板、注解、配置项。

中版本更新如 1.0 到 1.1 将兼容旧版本的模板和注解，配置项变动将提供更新指南。

大版本更新可能修改模板格式、一些注解和生成规则等。

帮助文档#

博客：Laravel 项目全自动接口管理（接口部分）（旧）

博客：Laravel 项目全自动接口管理（常用注解与对应生成代码） （旧）

本作品采用《CC 协议》，转载必须注明作者和本文链接