Laravel JSON API 伺服器建置指南
安裝與設定
首先，您需要安裝Laravel框架。使用Composer安裝Laravel：
composer create-project laravel/laravel api-project
cd api-project
建立資料庫結構
在建立API之前，需要設定資料庫連接。編輯.env檔案設定資料庫連接參數：
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database
DB_USERNAME=your_username
DB_PASSWORD=your_password
然後建立migration檔案來定義資料表結構：
php artisan make:migration create_products_table
在migration檔案中定義資料表結構：
public function up()
{
Schema::create('products', function (Blueprint $table) {
$table->id();
$table->string('name');
$table->text('description');
$table->decimal('price', 8, 2);
$table->timestamps();
});
}
執行migration建立資料表：
php artisan migrate
建立模型
建立對應的Eloquent模型：
php artisan make:model Product
建立API控制器
建立一個API控制器來處理請求：
php artisan make:controller Api/ProductController --api
在控制器中實現CRUD操作：
<?php
namespace App\Http\Controllers\Api;
use App\Http\Controllers\Controller;
use App\Models\Product;
use Illuminate\Http\Request;
class ProductController extends Controller
{
public function index()
{
$products = Product::all();
return response()->json($products);
}
public function store(Request $request)
{
$validated = $request->validate([
'name' => 'required|string|max:255',
'description' => 'required|string',
'price' => 'required|numeric'
]);
$product = Product::create($validated);
return response()->json($product, 201);
}
public function show(Product $product)
{
return response()->json($product);
}
public function update(Request $request, Product $product)
{
$validated = $request->validate([
'name' => 'sometimes|string|max:255',
'description' => 'sometimes|string',
'price' => 'sometimes|numeric'
]);
$product->update($validated);
return response()->json($product);
}
public function destroy(Product $product)
{
$product->delete();
return response()->json(null, 204);
}
}
定義API路由
在routes/api.php檔案中定義API路由：
<?php
use App\Http\Controllers\Api\ProductController;
use Illuminate\Support\Facades\Route;
Route::apiResource('products', ProductController::class);
這將自動生成以下路由：
- GET /api/products - 獲取所有產品
- POST /api/products - 創建新產品
- GET /api/products/{product} - 獲取單個產品
- PUT/PATCH /api/products/{product} - 更新產品
- DELETE /api/products/{product} - 刪除產品
API認證
如需API認證，可以使用Laravel Sanctum：
composer require laravel/sanctum
php artisan vendor:publish --provider="Laravel\Sanctum\SanctumServiceProvider"
php artisan migrate
在app/Models/User.php中添加Sanctum特性：
use Laravel\Sanctum\HasApiTokens;
class User extends Authenticatable
{
use HasApiTokens, HasFactory, Notifiable;
// ...
}
API授權
在控制器中添加授權檢查：
public function __construct()
{
$this->middleware('auth:sanctum')->except(['index', 'show']);
}
API版本控制
在路由檔案中可以實現API版本控制：
Route::prefix('v1')->group(function () {
Route::apiResource('products', ProductController::class);
});
API資源轉換
使用API資源轉換器格式化回應：
php artisan make:resource ProductResource
編輯資源類：
<?php
namespace App\Http\Resources;
use Illuminate\Http\Resources\Json\JsonResource;
class ProductResource extends JsonResource
{
public function toArray($request)
{
return [
'id' => $this->id,
'name' => $this->name,
'description' => $this->description,
'price' => $this->price,
'created_at' => $this->created_at,
'updated_at' => $this->updated_at
];
}
}
在控制器中使用資源：
public function index()
{
$products = Product::all();
return ProductResource::collection($products);
}
public function show(Product $product)
{
return new ProductResource($product);
}
API文檔生成
可以使用L5-Swagger套件生成API文檔：
composer require darkaonline/l5-swagger
php artisan vendor:publish --provider "L5Swagger\L5SwaggerServiceProvider"
在控制器中添加Swagger註解：
/**
* @OA\Get(
* path="/api/products",
* summary="獲取所有產品",
* @OA\Response(response=200, description="成功獲取產品列表")
* )
*/
public function index()
{
// ...
}
API測試
建立API測試：
php artisan make:test ProductApiTest
編寫測試案例：
<?php
namespace Tests\Feature;
use App\Models\Product;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
class ProductApiTest extends TestCase
{
use RefreshDatabase;
public function test_can_get_all_products()
{
Product::factory()->count(3)->create();
$response = $this->getJson('/api/products');
$response->assertStatus(200)
->assertJsonCount(3);
}
// 更多測試...
}
常見Laravel API套件
以下是一些有用的Laravel API開發套件：
| 套件名稱 | 說明 | 連結 |
|---|---|---|
| Laravel Sanctum | 輕量級API認證系統 | https://laravel.com/docs/sanctum |
| Laravel Passport | 完整的OAuth2伺服器實現 | https://laravel.com/docs/passport |
| Fractal | API轉換層 | https://github.com/spatie/laravel-fractal |
| L5-Swagger | API文檔生成器 | https://github.com/DarkaOnLine/L5-Swagger |
| Laravel CORS | 跨域資源共享支援 | https://github.com/fruitcake/laravel-cors |
API最佳實踐
- 使用恰當的HTTP狀態碼
- 實施資料驗證
- 使用分頁來處理大型集合
- 實施速率限制以防止濫用
- 使用一致的命名約定
- 實施適當的錯誤處理
- 使用API資源進行資料轉換
- 實施快取以提高性能
以上步驟將幫助您使用Laravel建立一個功能完整、安全且高效的JSON API伺服器。