| 1 | package Mojolicious::Plugin::Crud; | ||
| 2 | 0 | ▶ | use Mojo::Base 'Mojolicious::Plugin'; |
|
Subroutine
BEGIN: called CC=1 SCAR=2.6
| |||
| 3 | |||
| 4 | use Lingua::EN::Inflect qw/PL/; | ||
| 5 | use Mojo::Util qw( camelize ); | ||
| 6 | |||
| 7 | #------------------------------------------------------------------------------ | ||
| 8 | # Crud 版本信息 | ||
| 9 | #------------------------------------------------------------------------------ | ||
| 10 | our $VERSION = '0.0.10'; | ||
| 11 | |||
| 12 | #------------------------------------------------------------------------------ | ||
| 13 | # Crud 插件注册方法 | ||
| 14 | #------------------------------------------------------------------------------ | ||
| 15 | sub register { | ||
| 16 | my ( $self, $app ) = @_; | ||
| 17 | |||
| 18 | # 注册 routes 快捷指令,接收定制属性 | ||
| 19 | $app->routes->add_shortcut( | ||
| 20 | api_routes => sub { | ||
| 21 | # 继承 $route | ||
| 22 | my $r = shift; | ||
| 23 | my $params = { @_ ? ( ref $_[0] ? %{ $_[0] } : @_ ) : () }; | ||
| 24 | |||
| 25 | # 提取参数 | ||
| 26 | my $name = $params->{name} or die "Parameter 'name' missing"; | ||
| 27 | my $readonly = $params->{readonly} || 0; | ||
| 28 | my $controller = $params->{controller} || $name; | ||
| 29 | |||
| 30 | # 转换为 controller 格式 | ||
| 31 | $controller = camelize($controller); | ||
| 32 | |||
| 33 | # 生成复数类型路由,并转换为小写 URI | ||
| 34 | my $route_part = $params->{route} || PL( $name, 10 ); | ||
| 35 | $route_part = lc($route_part); | ||
| 36 | $app->log->info("Creating Routes for resource '$name' (controller => $controller)"); | ||
| 37 | |||
| 38 | # 生成路由后丢给控制器 | ||
| 39 | my $resource = $r->route("/$route_part")->to( "controller" => $controller ); | ||
| 40 | |||
| 41 | #------------------------------------------------------ | ||
| 42 | # 接收 GET 请求,对应前端数据查询请求 | ||
| 43 | #------------------------------------------------------ | ||
| 44 | $resource->get->to('#get')->name("get_$route_part"); | ||
| 45 | $app->log->debug( " GET " . $r->to_string . "/$route_part (api_get)" ); | ||
| 46 | |||
| 47 | # 后端路由是否只读 | ||
| 48 | if ( !$readonly ) { | ||
| 49 | #------------------------------------------------------ | ||
| 50 | # 接收 POST 请求,对应前端新增数据请求 | ||
| 51 | #------------------------------------------------------ | ||
| 52 | $resource->post->to('#create')->name("create_$name"); | ||
| 53 | $app->log->debug( " POST " . $r->to_string . "/$route_part (api_create)" ); | ||
| 54 | |||
| 55 | #------------------------------------------------------ | ||
| 56 | # 接收 DELETE 请求,对应前端删除数据请求 | ||
| 57 | #------------------------------------------------------ | ||
| 58 | $resource->delete->to('#delete')->name("delete_$name"); | ||
| 59 | $app->log->debug( " DELETE " . $r->to_string . "/$route_part/ (api_delete)" ); | ||
| 60 | |||
| 61 | #------------------------------------------------------ | ||
| 62 | # 接收 PUT 请求,对应前端更新数据请求 | ||
| 63 | #------------------------------------------------------ | ||
| 64 | $resource->put->to('#update')->name("update_$name"); | ||
| 65 | $app->log->debug( " PUT " . $r->to_string . "/$route_part/ (api_update)" ); | ||
| 66 | } | ||
| 67 | |||
| 68 | # 检测是否为 download 路由 | ||
| 69 | $resource = $r->under( | ||
| 70 | "/$route_part/download" => sub { | ||
| 71 | my $c = shift; | ||
| 72 | $c->app->log->debug("Download: resource /$route_part/download"); | ||
| 73 | return 1; | ||
| 74 | } | ||
| 75 | )->to( controller => $controller ); | ||
| 76 | |||
| 77 | #------------------------------------------------------ | ||
| 78 | # 接收 GET 请求,处理 download 表单下载 | ||
| 79 | #------------------------------------------------------ | ||
| 80 | $resource->get->to("#download")->name("download_$name"); | ||
| 81 | $app->log->debug( " GET " . $r->to_string . "/$route_part/download (api_download)" ); | ||
| 82 | |||
| 83 | # 返回 CRUD + Download 样式路由 | ||
| 84 | return $resource; | ||
| 85 | } | ||
| 86 | ); | ||
| 87 | } | ||
| 88 | |||
| 89 | 1; | ||
| 90 | |||
| 91 | =head1 NAME | ||
| 92 | |||
| 93 | Mojolicious::Plugin::RESTRoutes - routing helper for RESTful operations | ||
| 94 | |||
| 95 | =head1 VERSION | ||
| 96 | |||
| 97 | version 0.0.10 | ||
| 98 | |||
| 99 | =head1 DESCRIPTION | ||
| 100 | |||
| 101 | This Mojolicious plugin adds a routing helper for | ||
| 102 | L<REST|http://en.wikipedia.org/wiki/Representational_state_transfer>ful | ||
| 103 | L<CRUD|http://en.wikipedia.org/wiki/Create,_read,_update_and_delete> | ||
| 104 | operations via HTTP to the app. | ||
| 105 | |||
| 106 | The routes are intended, but not restricted to be used by AJAX applications. | ||
| 107 | |||
| 108 | =head1 MOJOLICIOUS SHORTCUTS | ||
| 109 | |||
| 110 | =head2 api_routes | ||
| 111 | |||
| 112 | Can be used to easily generate the needed RESTful routes for a resource. | ||
| 113 | |||
| 114 | my $r = $self->routes; | ||
| 115 | my $userroute = $r->api_routes(name => 'user'); | ||
| 116 | |||
| 117 | # Installs the following routes (given that $r->namespaces == ['My::Mojo']): | ||
| 118 | # GET /users --> My::Mojo::User::rest_list() | ||
| 119 | # POST /users --> My::Mojo::User::rest_create() | ||
| 120 | # GET /users/:userid --> My::Mojo::User::rest_show() | ||
| 121 | # PUT /users/:userid --> My::Mojo::User::rest_update() | ||
| 122 | # DELETE /users/:userid --> My::Mojo::User::rest_remove() | ||
| 123 | |||
| 124 | I<Please note>: the english plural form of the given C<name> attribute will be | ||
| 125 | used in the route, i.e. "users" instead of "user". If you want to specify | ||
| 126 | another string, see parameter C<route> below. | ||
| 127 | |||
| 128 | You can also chain C<api_routes>: | ||
| 129 | |||
| 130 | $userroute->api_routes(name => 'hat', readonly => 1); | ||
| 131 | |||
| 132 | # Installs the following additional routes: | ||
| 133 | # GET /users/:userid/hats --> My::Mojo::Hat::rest_list() | ||
| 134 | # GET /users/:userid/hats/:hatid --> My::Mojo::Hat::rest_show() | ||
| 135 | |||
| 136 | The target controller has to implement the following methods: | ||
| 137 | |||
| 138 | =over 4 | ||
| 139 | |||
| 140 | =item * | ||
| 141 | |||
| 142 | C<rest_list> | ||
| 143 | |||
| 144 | =item * | ||
| 145 | |||
| 146 | C<rest_create> | ||
| 147 | |||
| 148 | =item * | ||
| 149 | |||
| 150 | C<rest_show> | ||
| 151 | |||
| 152 | =item * | ||
| 153 | |||
| 154 | C<rest_update> | ||
| 155 | |||
| 156 | =item * | ||
| 157 | |||
| 158 | C<rest_remove> | ||
| 159 | |||
| 160 | =back | ||
| 161 | |||
| 162 | B<Parameters to control the route creation> | ||
| 163 | |||
| 164 | =over | ||
| 165 | |||
| 166 | =item name | ||
| 167 | |||
| 168 | The name of the resource, e.g. a "user", a "book" etc. This name will be used to | ||
| 169 | build the route URL as well as the controller name (see example above). | ||
| 170 | |||
| 171 | =item readonly (optional) | ||
| 172 | |||
| 173 | If set to 1, no create/update/delete routes will be created | ||
| 174 | |||
| 175 | =item controller (optional) | ||
| 176 | |||
| 177 | Default behaviour is to use the resource name to build the CamelCase controller | ||
| 178 | name (this is done by L<Mojolicious::Routes::Route>). You can change this by | ||
| 179 | directly specifying the controller's name via the I<controller> attribute. | ||
| 180 | |||
| 181 | Note that you have to give the real controller class name (i.e. CamelCased or | ||
| 182 | whatever you class name looks like) including the full namespace. | ||
| 183 | |||
| 184 | $r->api_routes(name => 'user', controller => 'My::Mojo::Person'); | ||
| 185 | |||
| 186 | # Installs the following routes: | ||
| 187 | # GET /users --> My::Mojo::Person::rest_list() | ||
| 188 | # ... | ||
| 189 | |||
| 190 | =item route (optional) | ||
| 191 | |||
| 192 | Specify a name for the route, i.e. prevent automatic usage of english plural | ||
| 193 | form of the C<name> parameter as the route component. | ||
| 194 | |||
| 195 | $r->api_routes(name => 'angst', route => 'aengste'); | ||
| 196 | |||
| 197 | # Installs the following routes (given that $r->namespaces == ['My::Mojo']): | ||
| 198 | # GET /aengste --> My::Mojo::Angst::rest_list() | ||
| 199 | |||
| 200 | =back | ||
| 201 | |||
| 202 | B<How to retrieve the parameters / IDs> | ||
| 203 | |||
| 204 | There are two ways to retrieve the IDs given by the client in your C<rest_show>, | ||
| 205 | C<rest_update> and C<rest_remove> methods. | ||
| 206 | |||
| 207 | Example request: C<GET /users/5/hats/no9> | ||
| 208 | |||
| 209 | 1. New way: the stash entry C<fm.ids> holds a hash with all ids: | ||
| 210 | |||
| 211 | package My::Mojo::Hats; | ||
| 212 | use Mojo::Base 'Mojolicious::Controller'; | ||
| 213 | |||
| 214 | sub rest_show { | ||
| 215 | use Data::Dump qw(dump); | ||
| 216 | print dump($self->stash('fm.ids')); | ||
| 217 | |||
| 218 | # { user => 5, hat => 'no9' } | ||
| 219 | } | ||
| 220 | |||
| 221 | 2. Old way: for each resource there will be a parameter C<***id>, e.g.: | ||
| 222 | |||
| 223 | package My::Mojo::Hat; | ||
| 224 | use Mojo::Base 'Mojolicious::Controller'; | ||
| 225 | |||
| 226 | sub rest_show { | ||
| 227 | my ($self) = @_; | ||
| 228 | my $user = $self->param('userid'); | ||
| 229 | my $hat = $self->param('hatid'); | ||
| 230 | return $self->render(text => "$userid, $hatid"); | ||
| 231 | |||
| 232 | # text: "5, no9" | ||
| 233 | } | ||
| 234 | |||
| 235 | Furthermore, the parameter C<idname> holds the name of the last ID in the route: | ||
| 236 | |||
| 237 | package My::Mojo::Hat; | ||
| 238 | use Mojo::Base 'Mojolicious::Controller'; | ||
| 239 | |||
| 240 | sub rest_show { | ||
| 241 | my $p_name = $self->param('idname'); | ||
| 242 | my $id = $self->param($p_name); | ||
| 243 | return $self->render(text => sprintf("%s = %s", $p_name, $id || '')); | ||
| 244 | |||
| 245 | # text: "hatid = 5" | ||
| 246 | } | ||
| 247 | |||
| 248 | =head1 METHODS | ||
| 249 | |||
| 250 | =head2 register | ||
| 251 | |||
| 252 | Adds the routing helper (called by Mojolicious). | ||
| 253 | |||
| 254 | =encoding utf8 | ||
| 255 | |||
| 256 | =head1 AUTHOR | ||
| 257 | |||
| 258 | |||
| 259 | WENWU YAN, C<< <careline at 126.com> >> | ||
| 260 | |||
| 261 | |||
| 262 | =head1 LICENSE AND COPYRIGHT | ||
| 263 | |||
| 264 | This software is Copyright (c) 2020 by WENWU YAN. | ||
| 265 | |||
| 266 | This is free software, licensed under: | ||
| 267 | |||
| 268 | The Artistic License 2.0 (GPL Compatible) | ||
| 269 | |||
| 270 | =cut | ||