public-docs/校天犬开发规范.md

校天犬开发规范

一 路由

1、命名为单词复数，多个单词组成用-分割

2、方法

create 添加之前查预备数据 store 添加 destroy 删除 update 更新 edit 编辑（更新之前查数据） index 对应没有权限判断的列表数据，首页等 list 后台用户调取数据列表（一般有权限判断）

其他方法命名以这些单词为基础，例如：storeItem，recordList 等等

3、每个路由要取一个唯一的名字，名字和路径类似，例如：study-banners.store

    // 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 处理后返回例如：

$activity = Activity::latest()->first();
$activity = new ActivityResource($activity);
return $this->success($activity);

resource 文档

3.2 直接返回数组数据

return $this->success([
   'no' => '20200702001164102',
]);

对应返回值如下：

// 单独数据体
{
    "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 直接返回消息

return $this->message('操作成功');

对应返回值如下：

{
    "status": "success",                // 成功返回固定值
    "code": 200,                        // 固定 200
    "msg": "操作成功",                  // 提示消息
    "msgTime": 1500,                   // 提示消息展示时长，表示 1.5 秒
}

3.4 返回分页信息操作

<?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);
	}
}

返回示例：

{
    "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、错误返回

error_msg('错误提示信息');

对应效果

{
    "status": "error",
    "code": 400,
    "msg": "错误提示信息",
    "msgTime": 1500,
    "server_time": 1594017221,
    "msgShow": false
}

三、其他规范

1、代码规范参考下面链接

代码规范

2、代码自动格式化

composer global require squizlabs/php_codesniffer

3、git 开发分支在 dev 分支，提交前先拉取