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;
    }

支持自定义数据类型

可以自由添加需要的参数规则，如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();
    }

用户逻辑实现

    /**
     * @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));
    }

正式版使用方式

安装

引入

composer require kamicloud/stub-api

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

使用

php artisan stub-api:install

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

cd bin
./initGenerator

使用jdk编译工具

./generate

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

配置

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

app/Providers/RouteServiceProvider.php

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

引入路由文件
routes/api.php

include_once 'generated_routes.php';

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

\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,

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

版本更新兼容性说明

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

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

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

帮助文档

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

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

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