前言

接口工具使用注解来增强接口表达能力。在一般情况下，一个注解只会产生一种效果，如表示数据字段可以为空（Optional）、强制从Eloquent中指定字段获取数据（DBField）、控制器使用指定中间件（Middlewares）等。

注解列表

元注解

@Extendable

该注解只能使用在注解上，被该注解修饰的注解会由父节点向子节点传递，而当子节点存在和父节点相同的注解时，子节点的注解会覆盖父节点注解。典型例子是Middlewares注解，在Contrller上使用Middlewares注解，其下的每个Action都将默认使用相同的Middlewares。

示例

@Retention(RetentionPolicy.RUNTIME)
@Extendable
public @interface Middleware {
String[] value() default "";
}

API级注解

@Middlewares(String[])

指示Controller/Action使用指定的中间件

示例

            @Middleware("auth")
            class GetUsers {
            }

生成代码效果

Route::match(['POST'], '/v1/user/get_users', 'V1\UserController@GetUsers')->middleware(['auth']);

@Methods(MethodType[])

表示HTTP请求类型

为了测试方便，所有接口都支持POST方式请求，调用方可以根据实际情况使用合适的方式。

参数

public enum MethodType {
    GET, POST, PUT, PATCH, DELETE, UPDATE;
}

示例

            @Methods({MethodType.POST})
            class GetUsers {
                @Request
                String[] strings;
                @Request
                int[] ints;
            }

生成代码效果

Route::match(['POST', 'POST'], '/v1/admin_user/get_users', 'V1\AdminUserController@GetUsers');

@Request / @Response

标注该数据字段应出现在请求中或响应中。

示例

            /**
             * 取得一篇文章
             */
            class GetArticle {
                @Request
                Integer id;
                @Response
                Models.Article article;
            }

生成代码

    public function requestRules()
    {
        return [
            ['title', 'title', 'bail|String', null],
            ['content', 'content', 'bail|String', null],
        ];
    }

    public function responseRules()
    {
        return [
            ['article', 'article', ArticleModel::class, Constants::IS_MODEL],
        ];
    }

模型注解

@DBField(String)

该注解只能用在字段上
当从json或Eloquent中初始化数据时，如果接口传递数据的key和数据来源的key不同，可以指定数据来源为参数中的key。
如果不使用该注解，默认获取small snake传递small camel。

示例

        /**
         * 模拟一个老师的信息
         */
        class Teacher {
            @DBField("id")
            int teacherId;
        }

生成效果

    public function getAttributeMap()
    {
        return [
            ['teacherId', 'id', 'bail|int', null],
        ];
    }

字段级注解

@Optional

表示字段是可以为空的，在数据字段自动过滤时，将允许空字段通过。

示例

        class Article {
            @Optional
            @Mutable
            Integer id;
        }

生成代码

    public function getAttributeMap()
    {
        return [
            ['id', 'id', 'nullable|bail|Integer', Constants::IS_OPTIONAL],
        ];
    }

枚举注解

@StringEnum

字段规则不使用自增ID，而改用实际对应的key。
示例

        @StringEnum
        enum PayWay {
            WECHAT,
            ALIPAY,
        }

生成代码

class PayWay extends Enum
{
    public const WECHAT = 'WECHAT';

    public const ALIPAY = 'ALIPAY';

    public const _MAP = [
        self::WECHAT => 'WECHAT',
        self::ALIPAY => 'ALIPAY',
    ];

}

@AsBO

将不止生成带版本信息的枚举，还会根据currentTemplate中的信息生成一份枚举代码（BO）。
后续将允许该注解使用在model上。

示例

        @StringEnum
        @AsBO
        enum PayWay {
            WECHAT,
            ALIPAY,
        }

生成代码

<?php

namespace App\Generated\BOs\Enums;

use YetAnotherGenerator\BOs\Enum;

class PayWay extends Enum
{
    public const WECHAT = 'WECHAT';

    public const ALIPAY = 'ALIPAY';

    public const _MAP = [
        self::WECHAT => 'WECHAT',
        self::ALIPAY => 'ALIPAY',
    ];

}

测试相关注解

@Mutable

在使用自动回归测试时，将会将字段转换为*，表示该字段不需要校验。

示例

        class Article {
            @Optional
            @Mutable
            Integer id;
            String title;
            @Optional
            String content;
            Models.User user;
            Enums.ArticleStatus status;
            @Optional
            Integer commentsCount;
            /**
             * 需要时用于标记是否收藏
             */
            @Optional
            Boolean favorite;
            /**
             * 是否是添加火热标记
             */
            @Optional
            Boolean hot;
            Date createdAt;
        }

效果

{
    "status": 0,
    "message": "success",
    "data": {
        "articles": [
            {
                "id": "*",
                "title": "nf1s4836nntQxE2oWWvk",
                "content": null,
                "user": {
                    "name": "Ttdnts",
                    "id": "*",
                    "avatar": "https://avatars3.githubusercontent.com/u/25639206?s=88&v=4"
                },
                "status": 1,
                "commentsCount": 1,
                "favorite": null,
                "hot": null,
                "createdAt": "2018-12-30 16:11:32"
            },

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