blib/lib/Mojolicious/Plugin/Crud.pm

filter: Statementstmt 33.3% 1 / 3 Branchbran n/a Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 1 / 1 Podpod n/a totaltotal 50.0% 2 / 4 CC 1 SCAR 2.6
CC
1
Cov
33%
BEGIN
1.3
CRAP 1.3
↑ Summary
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
↑ Summary