laravel-annotation (版本小于php8)是基于多行注释+PHP反射机制实现注解功能,已发布的注解有:
- Route(路由)、Group(路由分组,包含路由中间件定义)、Node(管理后台菜单树和权限结点)、Inject(依赖注入)、Validation(验证器)。
- 使用注解可以提高开发效率,减少重复的无用工作。
支持laravel版本 >= 5.8,php版本 >= 7.1
- composer require crastlin/laravel-annotation:v2.1beta
- 或在composer.json中的require添加 "crastlin/laravel-annotation":"^v2.1beta"
定义规则
- 使用Route/RequestMapping/PostMapping/GetMapping/OptionsMapping注解定义路由
- 生成的路由文件在项目根目录的data/routes/{模块名}/route.php
- 同时会生成自定义路由对应控制器规则的别名文件 alias.php
- 路由注解仅支持方法注解,定义在class无效
- 使用PHP Storm时,在settings / Plugins 中搜索php-annotations,使用时会有相应的提示。
注解例子1
class IndexController
{
/**
* @Route(url="login", method="post")
*/
function index()
{
// todo
}
}
或者
class IndexController
{
/**
* @PostMapping("login")
*/
function index(){
// todo
}
}
以上两种注解生成的路由配置结果相同:
Route::post('login', 'IndexController@index')->name('index.index');
- 说明:如果不定义url或value,则默认为:{当前控制器}(不含Controller)/{方法名}作为url
注解例子2
class IndexController
{
/**
* @PostMapping("article/{cate}")
*/
function index(){
}
/**
* @PostMapping("article/{cate}/{id}/{page?}")
*/
function detail(){
// todo
}
}
以上两种注解生成的路由配置结果相同:
Route::post('article/{cate}', 'IndexController@index')->name('index.index');
Route::post('article/{cate}/{id}/{page?}', 'IndexController@detail')->name('index.detail');
定义规则
- 使用Group() 支持Json格式或按字段传值注解定义路由闭包分组
- 路由分组注解支持类注解和方法注解
注解例子
/**
* @Group(prefix="home", namespace="Home", middleware="user.check", as="User::", domain="xxx.com")
*/
class IndexController
{
/**
* @Route(url=login, method=post|get)
*/
function index()
{
// todo
}
/**
* @RequestMapping("reg")
*/
function register()
{
// todo
}
/**
* @GetMapping
*/
function userCenter()
{
// todo
}
}
或者使用json格式
/**
* @Group({"prefix":"home", "namespace":"Home", "middleware": "user.check", "as": "User::"})
*/
class IndexController
{
/**
* @Group({"limit": true})
* @Route(url=login, method=post|get)
*/
function index()
{
// todo
}
/**
* @Group({"limit": true})
* @RequestMapping("reg")
*/
function register()
{
// todo
}
/**
* @GetMapping
*/
function userCenter()
{
// todo
}
}
- 说明:
- 使用类定义Group注解时,则当前控制器的所有公共带路由注解的方法都会在这个闭包内;
- 而在方法定义Group注解时,仅当前方法在闭包内;
- 所有定义相同的Group参数的路由,会自动放在同一个Group闭包内 以上定义生成的路由为:
Route::group(["preifx" => "home", "namespace" => "Home", "middleware" => "user.check", "as" => "User::"], function(){
Route::group(["limit" => true], function(){
Route::match(['GET', 'POST'], 'login', 'IndexController@index');
Route::match(['GET', 'POST'], 'reg','IndexController@register');
});
Route::get('Index/userCenter','IndexController@userCenter');
});
// ...
- 可以通过命令生成配置文件,config/annotation
php artisan annotation:config
配置说明
- 以下为注解全局配置
- 控制器目录,默认为:app/Http/Controllers
- 根命名空间,默认为:App\Http\Controllers
- 需要扫描的模块目录名称数组,默认为:Admin
- 生成文件根目录,默认为:data
- 是否开启自动生成(建议debug模式下开启)请求时将自动创建新增加的注解到路由表,默认为:env('APP_DEBUG')
- 根路由分组,默认不分组,定义格式为
return [
'modules' => ['User', 'Admin'],
'root_group' => [
'User' => [
['prefix' => 'user', 'namespace' => 'User', 'middleware' => 'user.check', 'as' => 'User::'],
// 更多分组
],
'Admin' => [
['prefix' => 'admin', 'namespace' => 'Admin', 'middleware' => 'admin.check', 'as' => 'Admin::'],
// 更多分组
],
],
];
- 请求时自动创建节点,默认关闭,可以配置环境 ANNOTATION_AUTO_CRATE_NODE=true 开启
命令说明
- 使用命令生成所有模块的路由映射文件,生产环境时建议使用此方式,如需指定生成模块,则在命令后输入模块名
php artisan annotation:route {module?}
- 在开发后台时,经常会需要使用到功能菜单和角色权限分配的功能,使用注解的好处在于,开发时定义好菜单树和权限节点信息,无需在数据库繁琐添加,只需要使用生成命令,快速将注解的菜单树和权限节点保存到数据库,方便环境切换和移植,为开发者整理菜单节约宝贵的时间。
定义规则
- 使用@node(name=菜单名称 ...) 定义为菜单节点
- 支持类注解和方法注解
类注解模块
/**
* @node (name="应用名称", parent="父节点", menu=0/1, auth=0/1/2, order=0, params="xx=yy&cc=ss", icon="xxx", remark="xxx", actions="defaultPage,xxx,yyyy")
*/
方法注解模块
/**
* @node (name="节点名称", parent="父节点", menu=0/1, auth=0/1/2, order=0, params="xx=yy&cc=ss", icon="xxx", code="query", remark="xxx", ignore, delete)
*/
参数说明
*(必须)注册节点名称, 如果使用子类名称,则需在子类的类注解定义 @node (name=xxx),实际名称 = 子类的类注解name + 当前方法name
*(可选)注册节点的父节点,如果不定义,则做为一级节点菜单, 默认父节点为当前控制器的defaultPage方法
*(可选)注册节点显示类型,0:不在左侧菜单显示(默认),1:显示左侧菜单;
*(可选)注册节点权限类型,0:只作为菜单,其它:验证权限(默认)
*(可选)菜单排序, menu为1时有效
(可选)菜单携带参数,格式为url参数格式
(可选)作为一级菜单时,定义图标
- (可选) 按钮权限控制代码,在admin_menu_permission表定义,默认为query
*(可选)备注功能信息
- (可选) 是否忽略扫描
- (可选) 删除节点,存在子节点时无效
- (可选) 多态方法继承时,通过此注解指定继承的方法名,name获取组合名={子类name注解}+{父类方法name注解}
特殊说明
- 如果值为0,可以只定义属性名称,例如:@node (name=xxx, menu, auth, order)
- 注解标记node和属性括号、参数间可以有空格
注解例子
class UserController
{
/**
* @Node(name="用户管理", menu=1, auth=0)
*/
function defaultPage()
{
// this method only for menu
}
/**
* @Node(name="用户列表", menu=1)
*/
function index()
{
// todo
}
/**
* @Node(name="编辑用户", parent="index")
*/
function setUserName()
{
// todo
}
}
- 说明
- defaultPage方法名为菜单根节点,他在父级ID parent_id=0
- 除defaultPage方法名,其它方法名都有父节点,当前控制器内其它方法不定义父节点时,则默认父节点为: defaultPage, index方法的父节点隐式parent=defaultPage
- setUserName方法为index的子节点,需要定义他的parent注解,默认为当前控制器,所以parent=index 等于 parent=User/index(tips: 如果方法父节点为其它控制器时,则需要定义控制器名,不含Controller后缀)
继承类使用
abstract class BaseController implements \LaravelAnnotationNodeInterface
{
/**
* @Node(menu=1, auth=0)
*/
function defaultPage()
{
// this method only for menu
}
}
/**
* @Node(name="用户管理", order=1)
*/
class UserController extends BaseController
{
/**
* @Node(name="用户列表", menu=1)
*/
function index()
{
// todo
}
/**
* @Node(name="编辑用户", parent="index")
*/
function setUserName()
{
// todo
}
}
- 以上User控制器类注解,会合并到继承defaultPage方法上
/**
* @Node(name="用户中心", menu=1, auth=0, order=1)
*/
function defaultPage()
{
// this method only for menu
}
多态控制器应用
- 多态应用时,类注解名name叠加
/**
* @Node(name="动物园", order=1)
*/
abstract class Animal extends BaseController
{
/**
* @Node(name="主页", menu=1)
*/
function index()
{
// todo
}
/**
* @Node(name="观看时间", menu=1)
*/
function schedule()
{
// todo
}
}
/**
* @Node(name="长颈鹿", actions=index, schedule)
*/
class GiraffeController extends Animal
{
}
/**
* @Node(name="老虎")
*/
class TigerController extends Animal
{
}
- 通过类注解的actions指定继承方法名,访问index时,name等于:长颈鹿主页、老虎主页,访问schedule时,name等于:长颈鹿观看时间、老虎观看时间。
- 生成所有模块的菜单树和权限节点,如果需要指定模块,则在命令后输入模块名称:
php artisan annotation:node {module?}
节点注解demo
- 请查看我的主页laravel-annotation-demo仓库获取,内附使用demo和需要使用的sql
- 经常遇到有些情况需要防止并发操作的应用场景,可以使用该注解创建原子操作锁,防止并发访问。
使用需要在app/Http/Kernel.php中增加中间件配置
class Kernel extends \Illuminate\Foundation\Http\Kernel
{
protected $middleware = [
// ...
Crastlin\LaravelAnnotation\Middleware\InterceptorMiddleware::class,
];
}
然后在控制器中定义规则
- 使用@SyncLock(expire=锁时间, ...)
- 只支持方法注解
参数说明
- (可选)锁key前缀名,默认为:sync_lock_annotation
*(可选)锁key名,默认为模块名+控制器名+方法名,完整的名称为:{prefix}_{name}
*(可选)锁后缀名,可解析输入参数变量,例如请求get id, 则可以使用: suffix="$id" 或者 suffix="get.$id" 或者 suffix="input.$id" 支持:input/get/post/put/delete/header等,其中input包含get/post/put/delete
*(可选)多个参数后缀,使用:suffix={"xxx", "yyy"},同样也支持解析输入变量,例如:suffixes={"$id", "header.$token", "post.name", ...}
*(可选)锁有效期,单位秒,默认为86400
(可选)是否自动释放锁,默认为否,即执行完成自动释放锁
(可选)拒绝时的响应数据,json格式,也可以单独配置code或msg,或者在config/annotation.php中配置lock => response
(可选)response中的自定义code
(可选)response中的自定义message
示例
class IndexController
{
/**
* @RequestMapping("test")
* @SyncLock(expire=30, suffix="$id")
*/
function test()
{
//todo
}
}
- 以上的效果是同一的id请求会限制并发
- 在项目开发中,经常需要往service或logic层传递数据,通常做法是使用setter,但多个对象setter时,会让代码过于冗余,且有可能会缺少某个setter而导致程序无法正常运行。
5.1 使用前需要对数据进行绑定,以下例子,在中间件绑定请求参数:
namespace App\Http\Middleware;
use Crastlin\LaravelAnnotation\Facades\Injection;
use \Illuminate\Http\Request;
use App\Model\User;
class AuthorizeCheck
{
function handle(Request $request)
{
$parameters = $request->getContent();
// todo something
// ...
// 绑定数据到依赖类容器
Injection::bind('parameters', $parameters);
// 绑定用户
try{
$user = User::find($parameters['uid']);
Injection::bind('user', $user);
}catch (\Throwable $throwable){
var_dump("用户不存在");
}
}
}
- 在控制器中依赖注入例子
// 基类配置注入方法
namespace Illuminate\Routing\Controller;
use Crastlin\LaravelAnnotation\Facades\Injection;
use Crastlin\LaravelAnnotation\Annotation\Annotations\Inject;
use Crastlin\LaravelAnnotation\Annotation\Annotations\PostMapping;
abstract class BaseController extends Controller
{
// 通用注入属性方法
function setProperty(string $name, $value)
{
if (property_exists($this, $name))
$this->{$name} = $value;
}
// 重写callAction
public function callAction($method, $parameters)
{
$input = Input::toArray();
// 解析当前控制器对象属性注解,并自动注入
Injection::injectWithObject($this);
// call controller action
return call_user_func_array([$this, $method], $parameters);
}
}
- 实现控制器类中使用注解自动注入
class IndexController extends BaseController
{
// 在以下属性增加Inject注解
/**
* @var array $parameters
* @Inject
*/
protected $parameters;
/**
* @PostMapping
*/
function index()
{
// 当前访问index方法时,可以直接访问注入的属性
var_dump($this->parameters);
// 使用take方法直接取值
$user = Injection::take('user');
var_dump($user);
// 使用exists判断容器是否绑定对象
$exists = Injection::exists('user');
var_dump($exists);
}
}
5.2 使用别名注入
class IndexController extends BaseController
{
// 在以下属性增加Inject注解
/**
* @var array $data
* @Inject(name="parameters")
*/
protected $data;
/**
* @PostMapping
*/
function index()
{
// 当前访问index方法时,可以直接访问注入的属性
var_dump($this->parameters);
}
}
5.3 使用前缀注入
// 在中间件中绑定带前缀的数据或对象
namespace App\Http\Middleware;
use Crastlin\LaravelAnnotation\Facades\Injection;
use \Illuminate\Http\Request;
class AuthorizeCheck
{
function handle(Request $request)
{
$parameters = $request->getContent();
// todo something
// ...
// 绑定数据到依赖类容器
Injection::bind('common.parameters', $parameters);
}
}
- 在对应属性增加注入注解
class IndexController extends BaseController
{
// 在以下属性增加Inject注解
/**
* @var array $data
* @Inject(name="common.parameters")
* 或者配置prefix
* @Inject(name="parameters", prefix="common")
*/
protected $data;
/**
* @PostMapping
*/
function index()
{
// 当前访问index方法时,可以直接访问注入的属性
var_dump($this->parameters);
}
}
5.4 使用单例方法:SingletonTrait 自动注入
namespace App\Service;
use Crastlin\LaravelAnnotation\Utils\Traits\SingletonTrait;
class BusinessService
{
use SingletonTrait;
/**
* @var array $data
* @Inject(name="common.parameters")
*/
protected $data;
function profile()
{
var_dump($this->data);
}
}
- 通过singleton方法实例化BusinessService对象,完成依赖注入
namespace App\Http\Controllers\Api;
use App\Service\BusinessService;
class IndexController extends BaseController
{
/**
* @PostMapping
*/
function index()
{
$service = BusinessService::singleton();
$service->profile();
}
}
5.5 依赖注入的优先级是:setter方法 -> setProperty方法 -> 直接赋值
namespace App\Service;
use Crastlin\LaravelAnnotation\Utils\Traits\SingletonTrait;
class BusinessService
{
use SingletonTrait;
/**
* @var array $data
* @Inject(name="common.parameters")
*/
protected $data;
// 使用set + 属性名(小驼峰命名规则)
function setData(?array $data)
{
// todo something
$this->data = $data;
}
function profile()
{
var_dump($this->data);
}
}
- 注意:使用赋值的方式注入时,须要属性为pubic 或者 增加魔术方法 __set()
5.6 方法依赖注入(v2.1beta新增)
namespace App\Service;
use Crastlin\LaravelAnnotation\Utils\Traits\SingletonTrait;
use App\Model\User;
class BusinessService
{
use SingletonTrait;
/**
* @var User $user
*/
protected $user;
/**
* @Inject(name="service.user")
*/
function takeUser(?User $user)
{
$this->user = $user;
}
function getUser()
{
var_dump($this->user);
}
}
- 可以通过注解的方式,为方法增加数据验证注解,需要更新到最新到2.1及以上版本。
6.1 在控制器中使用
- 在app/Http/Kernel.php中引入拦截器中间件
class Kernel extends \Symfony\Component\HttpKernel\HttpKernel
{
protected $middleware = [
// ....
// 引入拦截器中间件
\Crastlin\LaravelAnnotation\Middleware\InterceptorMiddleware::class,
];
}
- 说明:如果已经引用了同步锁中间件 \Crastlin\LaravelAnnotation\Middleware\SyncLockMiddleware::class, 因为拦截器中间件包含同步锁功能, 所以需要将该中间件移除。
- 在控制器对应的方法添加注解
namespace App\Http\Controllers\Api;
use App\Service\BusinessService;
use Crastlin\LaravelAnnotation\Annotation\Annotations\Validation;
class IndexController extends BaseController
{
/**
* @PostMapping
* @Validation(field="username", rule="required", message="用户名不能为空")
* @Validation(field="mobile", rule="required|regex:~^1\d{10}$~", attribute="手机号", message=":attribute不能为空|:attribute格式不正确")
*/
function index()
{
}
}
- 定义多个验证规则
namespace App\Http\Controllers\Api;
use App\Service\BusinessService;
use Crastlin\LaravelAnnotation\Annotation\Annotations\Validation;
class IndexController extends BaseController
{
/**
* @PostMapping
* @Validation(field="mobile", rule="required|regex:~^1\d{10}$~", attribute="手机号", message=":attribute不能为空|:attribute格式不正确")
*/
function index()
{
}
}
- 使用自定义验证类注解
namespace App\Http\Controllers\Api;
use App\Service\BusinessService;
use Crastlin\LaravelAnnotation\Annotation\Annotations\Validation;
class IndexController extends BaseController
{
/**
* @PostMapping
* @Validation(class="Mobile")
*/
function index()
{
}
}
- 在app/Validator目录下创建自定义验证器
namespace App\Validator;
use App\Service\BusinessService;
use Crastlin\LaravelAnnotation\Utils\Validate;
class Mobile extends Validate
{
protected $rules = [
'mobile' => 'required|regex:/^1[3456789][0-9]{9}$/',
'code' => 'required|digits_between:3,6',
],
$messages = [
'required' => ':attribute不能为空',
'mobile.regex' => ':attribute输入不正确',
'code.digits_between' => ':attribute必须为3到6位',
],
$attributes = [
'mobile' => '手机号',
'code' => '验证码',
];
}
- 说明:自定义验证器目录可在config/annotation中配置 interceptor -> validate -> namespace,验证需要继承:\Crastlin\LaravelAnnotation\Utils\Validate 类
- 其它验证器注解
namespace App\Http\Controllers\Api;
use App\Service\BusinessService;
use Crastlin\LaravelAnnotation\Annotation\Annotations\Validation;
class IndexController extends BaseController
{
/**
* @PostMapping
* @Validation\Required(username)
* @Validation\AlphaNum(username)
* @Validation\Regex(field="username", rule="~^\w{6,20}$~")
*/
function index()
{
}
}
- 请查看Annotation/Annotations/Validation目录
6.2 自定验证注解
- 在指定类中使用验证器注解,可以定义__invoke调用:\Crastlin\LaravelAnnotation\Facades\Validation::runValidation 方法,或者在使用类中引用:Crastlin\LaravelAnnotation\Utils\Traits,然后在__invoke方法中调用 $this->invokeValidation($method,$data) 方法
- 使用此插件请遵守法律法规,请勿在非法和违法应用中使用,产生的一切后果和法律责任均与作者无关!