編寫具有描述性的 RESTful API (一): Workflow

這是個系列,將會以結構較為簡單明瞭的簡書為參考,編寫一套簡潔,可讀的社群型別的 RESTful API.

我使用的laravel版本是5.7, 且使用 tree-ql 作為api開發基礎工具.

該系列並不會一步一步來教你怎麼實現,只會闡明一些基本點,以及一些關鍵的地方

相關的程式碼我會放在 weiwenhao/community-api 你可以隨時參閱一些細節部分

開始咯

建表

先來看看**設計稿**,根據設計稿可以設計出基礎的帖子表結構. 當然這不會是最終的表結構,後面會根據實際情況來一點點完善該表.

Schema::create('posts', function (Blueprint $table) {
    $table->increments('id');
    $table->string('code')->index();
    $table->string('title');
    $table->string('description');
    $table->text('content')->nullable();
    $table->string('cover')->nullable();
    $table->unsignedInteger('comment_count')->default(0)->comment('評論數量');
    $table->unsignedInteger('like_count')->default(0)->comment('點贊數量');
    $table->unsignedInteger('read_count')->default(0)->comment('閱讀數量');
    $table->unsignedInteger('word_count')->default(0)->comment('字數');
    $table->unsignedInteger('give_count')->default(0)->comment('讚賞數量');

    $table->unsignedInteger('user_id')->index();

    $table->timestamp('published_at')->nullable()->comment('釋出時間');
    $table->timestamp('selected_at')->nullable()->comment('是否精選/精選時間');
	$table->timestamp('edited_at')->nullable()->comment('內容編輯時間');
    
    $table->timestamps();
});
複製程式碼

然後看看評論表.簡書的評論並不是無限級的,而是分為兩層,結構簡單.

Schema::create('comments', function (Blueprint $table) {
    $table->increments('id');
    $table->text('content');
    $table->unsignedInteger('user_id')->index();
    $table->unsignedInteger('post_id')->index();
    $table->unsignedInteger('like_count')->default(0);
    $table->unsignedInteger('reply_count')->default(0);
    $table->unsignedInteger('floor')->comment('樓層');
    $table->unsignedInteger('selected')->comment('是否精選')->default(0);
    $table->timestamps();
});

Schema::create('comment_replies', function (Blueprint $table) {
    $table->increments('id');
    $table->unsignedInteger('comment_id')->index();
    $table->unsignedInteger('user_id')->index();
    $table->text('content');
    $table->json('call_user')->nullable()->comment('@使用者,{id: null, nickname: null}');
    $table->timestamps();
});
複製程式碼

然後是使用者表

Schema::create('users', function (Blueprint $table) {
    $table->increments('id');
    $table->string('nickname');
    $table->string('avatar');
    $table->string('email');
    $table->string('phone_number');
    $table->string('password');

    $table->unsignedInteger('follow_count')->default(0)->comment("關注了多少個使用者");
    $table->unsignedInteger('fans_count')->default(0)->comment("擁有多少個粉絲");
    $table->unsignedInteger('post_count')->default(0);
    $table->unsignedInteger('word_count')->default(0);
    $table->unsignedInteger('like_count')->default(0);

    $table->json('oauth')->nullable()->comment("第三方登入");

    $table->timestamps();
});
複製程式碼

為什麼從資料庫上開始設計?

從軟體開發的角度來說,資料是固有存在的,不會隨著互動與設計的變化而變化. 所以對於後端來說有了產品文件,就可以設計出接近完整的資料結構和80%左右的API了.

建模

建立相關的Model 及關聯關係

這裡需要多做一步,建立一個**Model基類**,其他的如 Post,Comment 繼承自該 Model . 當然我們不是要讓 Model 成為一個 Super 類,只是通過該 Model 獲得對其他 Model 的統一配置權.

已 Comment 為例

# Comment.php

<?php

namespace App\Models;


class Comment extends Model
{
    public function user()
    {
        return $this->belongsTo(User::class);
    }

    public function replies()
    {
        return $this->hasMany(CommentReply::class);
    }

    public function post()
    {
        return $this->belongsTo(Post::class);
    }
}
複製程式碼

其他的 Model 參考原始碼即可

填充 Seeder

為了讓前端更加順暢的除錯 api,seeder 是必不可少的一步. 接下來我們需要為上面建的幾張表新增相應的 factory 和 seeder

以 CommentFactory 為例

# CommentFactory.php

<?php

use Faker\Generator as Faker;

$factory->define(\App\Models\Comment::class, function (Faker $faker) {
    static $i = 1;
    return [
        'post_id' => mt_rand(1, \App\Models\Post::count()),
        'user_id' => mt_rand(1, \App\Models\User::count()),
        'content' => $faker->sentence,
        'like_count' => mt_rand(0, 100),
        'reply_count' => mt_rand(0, 10),
        'floor' => $i++,
        'selected' => mt_rand(1, 10) > 2 ? 0 : 1
    ];
});
複製程式碼

相應的 CommentSeeder

# CommentSeeder.php

<?php

use Illuminate\Database\Seeder;

class CommentSeeder extends Seeder
{
    /**
     * Run the database seeds.
     *
     * @return void
     */
    public function run()
    {
        factory(\App\Models\Comment::class, 1000)->create();
    }
}
複製程式碼

其他的 factory 和 seeder 參考原始碼呀

Seeder 的規範命名應該是 CommentsTableSeeder.php ,請不要學我!

發射

確定 API

還是先來看看設計稿 , 來建立第一批 API

初步來看文章詳情頁分為三部分. 文章內容部分,評論回覆部分,和推薦閱讀部分.由於我們目前只建了幾張基本表,所以先忽略推薦閱讀部分.

API 設計的一個原則是同一個頁面不要請求太多次 API ,否則會給伺服器帶來很大的壓力.但也不能是一條非常聚合的api包含一個頁面所有的資料. 這樣則失去了 API 的靈活與獨立性. 也不符合 RESTFul API 的設計思路

RESTFul API 是面向資源/資料的,是對資源的增刪改查. 而不是面向介面/具體的業務邏輯

所以上面說從設計稿切入實際是有些誤導的,原則上是不需要設計稿的.這裡的目的是為了推動文章向下進行,且能夠更快的看到成果

按照 tree-ql 的風格,我設計了這樣兩條 API

api.test.com/api/posts/{…

上面的api是真實可以點選測試的,你可以隨意修改include中的欄位,來觀察API的變化

執行請求的詳細資訊可以通過 telescope 檢視

我們來解讀一下上面兩條 API

取出帖子 {post},並且包含該帖子的詳情,使用者(使用者需要包含描述)和這篇帖子的所有精選評論
取出帖子 {post}下的評論,並且每條評論需要包含相關使用者和回覆/限制三條(回覆需要包含相關使用者)

毫不知羞恥的說,上面的API是極其富於可讀性的,並且有了 include 的存在,可控性也達到了非常高的地步

路由

# api.php

Route::get('posts/{post}', 'PostController@show');

Route::get('posts/{post}/comments', 'CommentController@index');
複製程式碼

還要為{post}進行路由模型繫結

# RouteServiceProvider.php

public function boot()
{
    parent::boot();
    
    Route::bind('post', function ($value) {
        // columns的作用稍後會解釋
        return Post::columns()->where('id', $value)->first();
    });
}
複製程式碼

控制器

由於沒有做版本控制,所以沒有新增類似Api/V1這樣的目錄. 以第二條 API 對應的控制器為例

# app/Http/Controllers/Api/CommentController

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Models\Comment;
use App\Resources\CommentResource;
use Illuminate\Http\Request;
use Illuminate\Http\Response;

class CommentController extends Controller
{
    /**
     * @param null $parent
     * @return \Weiwenhao\TreeQL\Resource
     */
    public function index($parent = null)
    {
        // 1.
        $query = $parent ? $parent->comments() : Comment::query();
        
        // 2.
        $comments = $query->columns()->latest()->paginate();

        // 3.
        return CommentResource::make($comments);
    }
}
複製程式碼

至此我們構成了 api.test.com/api/posts/{… 這條路由的訪問控制器,但此時還不能include任何東西.在說明如何定義include之前,我們先對控制器中的三處標註進行講解.

進行了路由模型繫結的相容處理,使得一個控制器可以相容多條路由. 具體可以參考優雅的使用路由模型繫結
這是常見的 Builder 查詢構造器,不嚴格討論的話 get() ∈ paginate(), 因此使用適用範圍更廣的 paginate 作為結果輸出. columns 是一個查詢作用域,由 tree-ql 提供,其賦予了精確查詢資料庫欄位的能力.
將查詢的結果集交付給 Resource, 此 Resource 並非 laravel 原生的 Resource,而是 tree-ql 提供的 Resource ,其會賦予我們 include 的能力,下面介紹一下該 Resource.

在閱讀下面的內容之前你需要閱讀一下 tree-ql 的文件

Resource

已 CommentResource 為例

# CommentResource.php

<?php

namespace App\Resources;

use Weiwenhao\TreeQL\Resource;

class CommentResource extends Resource
{
    protected $default = [
        'id', 
        'content', 
        'user_id', 
        'like_count',
        'reply_count',
        'floor'
    ];

    protected $columns = [
        'id', 
        'content', 
        'user_id', 
        'post_id', 
        'like_count',
        'reply_count', 
        'floor'
    ];

    protected $relations = [
        'user',
        'replies' => [
            'resource' => CommentReplyResource::class,
        ]
    ];
}
複製程式碼

其中 columns 代表著 comments 表的欄位, relations 定義的內容為代表 comment 模型中已經定義的關聯關係.

API 請求中有些資料每次都需要載入,因此 default 中定義的欄位會被預設 include ,而不需要在 url 中顯式的定義.

由於 CommentResource 的 relations 部分還依賴了 user 和 replies ,按照 tree-ql 的規則我們需要分別定義 UserResource 和 RepliesResource.

# UserResource.php

<?php

namespace App\Resources;

use Weiwenhao\TreeQL\Resource;

class UserResource extends Resource
{
    protected $default = ['id', 'nickname', 'avatar'];

    protected $columns = ['id', 'nickname', 'avatar', 'password'];
}

複製程式碼

# CommentReplyResource.php

<?php

namespace App\Resources;

use Weiwenhao\TreeQL\Resource;

class CommentReplyResource extends Resource
{
    protected $default = ['id', 'comment_id', 'user_id', 'content', 'call_user'];

    protected $columns = ['id', 'comment_id', 'user_id', 'content', 'call_user'];

    protected $relations = ['user'];

    /**
     * ...{post}/comments?include=...replies(limit:3)...
     *
     * ↓ ↓ ↓
     *
     * $comments->load(['replies' => function ($builder) {
     *      $this->loadConstraint($builder, ['limit' => 3])
     * });
     *
     * ↓ ↓ ↓
     * @param $builder
     * @param array $params
     */
    public function loadConstraint($builder, array $params)
    {
        isset($params['limit']) && $builder->limit($params['limit']);
    }
}
複製程式碼

wo~, 我們已經完成了程式碼編寫,客戶端可以請求API了 …… 嗎?

再來品味一下第二條api, 取出帖子 {post}下的評論,且每條評論攜帶3條回覆, ORM(MySQL) 可以做到這樣的事情嗎?

點我看答案

這裡我選擇了 PLAN C ,至此我們才算完成第二條api的編寫,愉快的 request 吧

但是

上面的API這麼花裡胡哨,會不會有效能問題?

來看看這條 API 的實際 SQL 表現,可以看到 SQL 符合預期,並沒有任何的 n+1 問題,在速度方面可以說是有保障的. 實際上只要按照 tree-ql 的規範,無論多麼花裡胡哨的 include ,都不會有效能問題.

除錯工具 laravel/telescope

Workflow

走完了一套流程,稍微總結一下↓

Workflow 中去掉了確定 API 這一步,因為我們只要按照 RESTful 編寫路由,按照 tree-ql 編寫 Resource , API 自然而然的就出來啦~

補充

文章詳情API

api.test.com/api/posts/{…

這裡的 selected_comment 意為精選的評論,簡書此處使用了單獨的 api 來請求精選的評論.但是考慮到一篇帖子的精選評論通常不會太多.因此我採用 include 的方式將精選評論與帖子一種返回.

帖子和精選評論之間的的關係就是 data 和 meta 的關係. 來看看相關的配置程式碼

# CommentResource.php

<?php

namespace App\Resources;

use Weiwenhao\TreeQL\Resource;

class PostResource extends Resource
{
    protected $default = [
        'id',
        'title',
        'description',
        'cover',
        'comment_count',
        'like_count',
        'user_id'
    ];

    protected $columns = [
        'id',
        'title',
        'description',
        'cover',
        'read_count',
        'word_count',
        'give_count',
        'comment_count',
        'like_count',
        'user_id',
        'content',
        'selected_at',
        'published_at'
    ];


    protected $meta = [
        'selected_comments'
    ];


    public function selectedComments($params)
    {
        $post = $this->getModel();

        $comments = $post->selectedComments;

        // 這裡的操作類似於 $comments->load(['user', 'replies.user'])
        // 但是load可不會幫你管理Column. 因此我們使用Resource來構造
        $commentResource = CommentResource::make($comments, 'user,replies.user');

        // getResponseData既獲取CommentResource解析後並構造後的結構陣列
        return $commentResource->getResponseData();
    }
}
複製程式碼