|
|
@@ -0,0 +1,220 @@
|
|
|
+# 校天犬开发规范
|
|
|
+## 一 路由
|
|
|
+### 1、命名为单词复数，多个单词组成用`-`分割
|
|
|
+
|
|
|
+### 2、方法
|
|
|
+`create` 添加之前查预备数据
|
|
|
+`store` 添加
|
|
|
+`destroy` 删除
|
|
|
+`update` 更新
|
|
|
+`edit` 编辑（更新之前查数据）
|
|
|
+`index` 对应没有权限判断的列表数据，首页等
|
|
|
+`list` 后台用户调取数据列表（一般有权限判断）
|
|
|
+
|
|
|
+其他方法命名以这些单词为基础，例如：`storeItem`，`recordList` 等等
|
|
|
+
|
|
|
+### 3、每个路由要取一个唯一的名字，名字和路径类似，例如：`study-banners.store`
|
|
|
+```php
|
|
|
+ // banner
|
|
|
+ Route::post('study-banners/store', 'StudyBannersController@store')->name('study-banners.store');
|
|
|
+ Route::post('study-banners/destroy', 'StudyBannersController@destroy')->name('study-banners.destroy');
|
|
|
+ Route::post('study-banners/update', 'StudyBannersController@update')->name('study-banners.update');
|
|
|
+ Route::post('study-banners/edit', 'StudyBannersController@edit')->name('study-banners.edit');
|
|
|
+ Route::post('study-banners/list', 'StudyBannersController@list')->name('study-banners.list');
|
|
|
+```
|
|
|
+## 2、控制器
|
|
|
+### 1、控制器命名为单词的复数，例如：`CardsController`
|
|
|
+### 2、所有接口控制器继承 `ApisController`
|
|
|
+### 3、返回值
|
|
|
+#### 3.1 返回模型数据要用`API RESOURCE` 处理后返回例如：
|
|
|
+```php
|
|
|
+$activity = Activity::latest()->first();
|
|
|
+$activity = new ActivityResource($activity);
|
|
|
+return $this->success($activity);
|
|
|
+```
|
|
|
+[resource 文档](https://learnku.com/docs/laravel/7.x/eloquent-resources/7503 "resource 文档")
|
|
|
+#### 3.2 直接返回数组数据
|
|
|
+```php
|
|
|
+return $this->success([
|
|
|
+ 'no' => '20200702001164102',
|
|
|
+]);
|
|
|
+```
|
|
|
+对应返回值如下：
|
|
|
+```json
|
|
|
+// 单独数据体
|
|
|
+{
|
|
|
+ "status": "success", // 成功返回固定值
|
|
|
+ "code": 200, // 固定 200
|
|
|
+ "data": { // 数据包
|
|
|
+ "no": "20200702001164102" // 具体数据
|
|
|
+ },
|
|
|
+ "msg": "操作成功", // 提示消息
|
|
|
+ "msgTime": 1500, // 提示消息展示时长，表示 1.5 秒
|
|
|
+}
|
|
|
+// 数据列表
|
|
|
+{
|
|
|
+ "status": "success", // 成功返回固定值
|
|
|
+ "code": 200, // 固定 200
|
|
|
+ "data": { // 接口主体数据包
|
|
|
+ {
|
|
|
+ "id": 1,
|
|
|
+ "desc": "最高50%佣金，日入千元不是梦",
|
|
|
+ "name": "高额佣金",
|
|
|
+ "image": "https://card.xmfinger.com/frontend/icons/vip_im.png"
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": 2,
|
|
|
+ "desc": "轻松拥有自己的线上商城",
|
|
|
+ "name": "商城功能",
|
|
|
+ "image": "https://card.xmfinger.com/frontend/icons/vip_shop.png"
|
|
|
+ },
|
|
|
+ },
|
|
|
+ "meta": { // 其他附带数据，用 meta 包含
|
|
|
+ "vip_privileges": [
|
|
|
+ {
|
|
|
+ "id": 1,
|
|
|
+ "desc": "最高50%佣金，日入千元不是梦",
|
|
|
+ "name": "高额佣金",
|
|
|
+ "image": "https://card.xmfinger.com/frontend/icons/vip_im.png"
|
|
|
+ },
|
|
|
+ {
|
|
|
+ "id": 2,
|
|
|
+ "desc": "轻松拥有自己的线上商城",
|
|
|
+ "name": "商城功能",
|
|
|
+ "image": "https://card.xmfinger.com/frontend/icons/vip_shop.png"
|
|
|
+ },
|
|
|
+ }
|
|
|
+ "msg": "操作成功", // 提示消息
|
|
|
+ "msgTime": 1500, // 提示消息展示时长，表示 1.5 秒
|
|
|
+}
|
|
|
+```
|
|
|
+#### 3.3 直接返回消息
|
|
|
+```php
|
|
|
+return $this->message('操作成功');
|
|
|
+```
|
|
|
+对应返回值如下：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "status": "success", // 成功返回固定值
|
|
|
+ "code": 200, // 固定 200
|
|
|
+ "msg": "操作成功", // 提示消息
|
|
|
+ "msgTime": 1500, // 提示消息展示时长，表示 1.5 秒
|
|
|
+}
|
|
|
+```
|
|
|
+#### 3.4 返回分页信息操作
|
|
|
+```php
|
|
|
+<?php
|
|
|
+use App\Api\Helpers\PaginateHelper;
|
|
|
+class AskLeavesController extends ApiController
|
|
|
+{
|
|
|
+ use PaginateHelper;
|
|
|
+ public function index(Request $request)
|
|
|
+ {
|
|
|
+ // 从路由获取当前机构，大部分方法都要用
|
|
|
+ $institution = get_institution_from_route();
|
|
|
+ // 当前授权的用户
|
|
|
+ $user = $request->user();
|
|
|
+ // 查询数据库，获取分页数据
|
|
|
+ $res = AskLeave::query()
|
|
|
+ ->where('child_id', $child->id)
|
|
|
+ ->orderBy('id', 'desc')
|
|
|
+ ->with('child', 'courseSetting', 'user')
|
|
|
+ ->paginate(12);
|
|
|
+ // 处理成统一格式的分页数据
|
|
|
+ $res = $this->paginate($res， AskLeaveResrouce::class);
|
|
|
+ // 其他附带数据
|
|
|
+ $res['meta']['child'] = new ChildResource($child);
|
|
|
+ // 返回
|
|
|
+ return $this->res( $res);
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+返回示例：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "status": "success",
|
|
|
+ "code": 200,
|
|
|
+ "data": [
|
|
|
+ {
|
|
|
+ "id": 130,
|
|
|
+ "count": 1,
|
|
|
+ "leaave": 0,
|
|
|
+ "leave": 0,
|
|
|
+ "reason": "有事不能来",
|
|
|
+ "date": "2019-12-10 00:00:00",
|
|
|
+ "date_name": "2019-12-10 周二",
|
|
|
+ "user_name": "onetobigs",
|
|
|
+ "course_setting_name": "幼儿书法",
|
|
|
+ "created_at": "2020-07-06 14:30:43",
|
|
|
+ "updated_at": "2020-07-06 14:30:43",
|
|
|
+ "created_date": "2020-07-06 周一"
|
|
|
+ }
|
|
|
+ ],
|
|
|
+ "links": {
|
|
|
+ "first": "http://xiaotq.demo/api/ask-leave/index?page=1",
|
|
|
+ "last": "http://xiaotq.demo/api/ask-leave/index?page=1",
|
|
|
+ "prev": null,
|
|
|
+ "next": null
|
|
|
+ },
|
|
|
+ "meta": {
|
|
|
+ "current_page": 1,
|
|
|
+ "form": 1,
|
|
|
+ "last_page": 1,
|
|
|
+ "path": "http://xiaotq.demo/api/ask-leave/index",
|
|
|
+ "per_page": 12,
|
|
|
+ "to": 1,
|
|
|
+ "total": 1,
|
|
|
+ "child": {
|
|
|
+ "id": 34,
|
|
|
+ "name": "媛媛",
|
|
|
+ "avatar": "https://wx.qlogo.cn/mmopen/vi_32/QNPjGP8JnqNUUuxzgFw9UM3xk44WDB4OXmxPyEpCNzrWDE8ibVIDeEmNSWd556He3Se4oBoGuJvN1ThtAw1Vo6Q/132",
|
|
|
+ "en_name": "",
|
|
|
+ "gender": 2,
|
|
|
+ "gender_name": "女",
|
|
|
+ "birthday": "2019-12-05",
|
|
|
+ "school": "",
|
|
|
+ "first_letter": "Y",
|
|
|
+ "relation": "爸爸",
|
|
|
+ "type": 1,
|
|
|
+ "type_name": "常规学员",
|
|
|
+ "status": 0,
|
|
|
+ "status_name": "正常",
|
|
|
+ "tags": [],
|
|
|
+ "phone": "13055246008",
|
|
|
+ "address": "软件园三期A区06栋(厦门市集美区)",
|
|
|
+ "signing": true,
|
|
|
+ "check": false
|
|
|
+ }
|
|
|
+ },
|
|
|
+ "msg": "操作成功",
|
|
|
+ "msgTime": 1500,
|
|
|
+ "server_time": 1594017047,
|
|
|
+ "msgShow": false
|
|
|
+}
|
|
|
+```
|
|
|
+### 4、错误返回
|
|
|
+```php
|
|
|
+error_msg('错误提示信息');
|
|
|
+```
|
|
|
+对应效果
|
|
|
+```json
|
|
|
+{
|
|
|
+ "status": "error",
|
|
|
+ "code": 400,
|
|
|
+ "msg": "错误提示信息",
|
|
|
+ "msgTime": 1500,
|
|
|
+ "server_time": 1594017221,
|
|
|
+ "msgShow": false
|
|
|
+}
|
|
|
+```
|
|
|
+## 三、其他规范
|
|
|
+### 1、代码规范参考下面链接
|
|
|
+[代码规范](https://learnku.com/docs/laravel-specification/7.x "代码规范")
|
|
|
+### 2、代码自动格式化
|
|
|
+```shell
|
|
|
+composer global require squizlabs/php_codesniffer
|
|
|
+```
|
|
|
+
|
|
|
+
|
|
|
+### 3、git 开发分支在 `dev` 分支，提交前先拉取
|
|
|
+
|
