🎤 Laravel RESTful API 设计的版本控制与请求限流策略讲座

欢迎来到今天的讲座！今天我们将一起探讨如何在 Laravel 中优雅地实现 RESTful API 的版本控制和请求限流。这就像给你的 API 穿上一件防弹衣，既能保护它不被滥用，又能确保不同版本的用户都能愉快地玩耍 😄。

如果你对 Laravel 和 RESTful API 还不太熟悉，别担心！我会尽量用通俗易懂的语言来解释这些概念。准备好了吗？我们开始吧！

---

🔍 第一部分：API 版本控制的重要性

假设你正在开发一个天气预报 API，最初的设计只支持查询当前温度。后来，你想加入湿度、风速等功能。如果直接修改原有的 API 路径或结构，可能会导致老用户的应用崩溃。这种情况就像你在餐厅里突然换了菜单，但没告诉顾客一样，场面会很尴尬 🙈。

为什么需要版本控制？

1. 向后兼容性：新功能不会影响旧版本用户的体验。
2. 灵活性：可以独立迭代每个版本的功能。
3. 清晰性：用户知道他们使用的是哪个版本的 API。

---

📌 如何实现 API 版本控制？

Laravel 提供了多种方式来实现 API 的版本控制。以下是几种常见的方法：

方法一：通过 URL 路径区分版本

这是最直观的方式。例如：

Route::prefix('v1')->group(function () {
    Route::get('/weather', [WeatherController::class, 'getCurrentTemperature']);
});

Route::prefix('v2')->group(function () {
    Route::get('/weather', [WeatherController::class, 'getFullWeatherDetails']);
});

• v1 是旧版本，只返回温度。
• v2 是新版本，返回更详细的天气信息。

优点：简单易懂，适合初学者。
缺点：URL 可能变得冗长。

---

方法二：通过 HTTP Header 区分版本

这种方式更加隐秘，适合追求简洁 URL 的开发者。例如：

Route::middleware('api.version')->group(function () {
    Route::get('/weather', [WeatherController::class, 'handleRequest']);
});

然后在中间件中检查 Accept Header：

public function handle($request, Closure $next)
{
    if ($request->header('Accept') === 'application/vnd.api.v2+json') {
        return $next($request);
    } else {
        return response()->json(['error' => 'Unsupported version'], 400);
    }
}

优点：保持 URL 清洁。
缺点：需要客户端配合发送正确的 Header。

---

方法三：通过 Query 参数区分版本

这种方法也很常见，尤其是在调试阶段。例如：

Route::get('/weather', function (Request $request) {
    $version = $request->query('version', 'v1');
    if ($version === 'v2') {
        // 返回 v2 数据
    } else {
        // 返回 v1 数据
    }
});

优点：易于实现，无需修改客户端代码。
缺点：可能不够优雅。

---

⏰ 第二部分：请求限流的必要性

想象一下，你的 API 成为了某个恶意爬虫的目标，每秒钟被调用几千次。服务器很快就会崩溃，就像一辆超载的公交车，轮胎都爆了 🚑。

什么是请求限流？

请求限流是一种保护机制，限制每个用户在一定时间内的请求次数。Laravel 提供了内置的中间件 throttle 来帮助我们实现这一点。

---

🛠 如何实现请求限流？

基础用法

在路由定义中添加 throttle 中间件即可：

Route::middleware('throttle:60,1')->group(function () {
    Route::get('/weather', [WeatherController::class, 'getCurrentTemperature']);
});

这段代码表示：每个 IP 地址每分钟最多允许请求 60 次。

---

高级用法：基于用户身份的限流

如果你的 API 支持用户认证，可以根据用户的身份设置不同的限流规则。例如：

Route::middleware('auth:api')->group(function () {
    Route::middleware('throttle:120,1')->group(function () {
        Route::get('/weather', [WeatherController::class, 'getFullWeatherDetails']);
    });
});

对于未登录的用户，可以设置更低的限流规则：

Route::middleware('throttle:30,1')->group(function () {
    Route::get('/weather', [WeatherController::class, 'getCurrentTemperature']);
});

---

自定义限流逻辑

如果你的需求更复杂，比如根据用户的订阅计划设置不同的限流规则，可以通过自定义中间件来实现：

namespace AppHttpMiddleware;

use Closure;
use IlluminateSupportFacadesRateLimiter;

class SubscriptionThrottle
{
    public function handle($request, Closure $next, $maxAttempts, $decayMinutes)
    {
        $key = $this->resolveRequestSignature($request);

        if (RateLimiter::tooManyAttempts($key, $maxAttempts)) {
            return response()->json(['error' => 'Too many attempts'], 429);
        }

        RateLimiter::hit($key, $decayMinutes * 60);

        return $next($request);
    }

    protected function resolveRequestSignature($request)
    {
        return sha1($request->user()?->id ?: $request->ip());
    }
}

---

📊 总结对比表

方法	实现难度	用户体验	推荐场景
URL 路径	★★	★★★	初学者，简单项目
HTTP Header	★★★	★★★★	大型项目，追求 URL 清洁
Query 参数	★	★★	调试阶段，快速实现
请求限流（基础）	★★	★★★★	保护 API 免受滥用
请求限流（高级）	★★★	★★★★★	根据用户身份动态调整限流规则

---

🎉 结语

今天我们学习了如何在 Laravel 中实现 API 的版本控制和请求限流。版本控制让你的 API 更加灵活和稳定，而请求限流则为你的 API 提供了一层重要的保护。

希望今天的讲座对你有所帮助！如果有任何问题，欢迎随时提问。记住，编程就像烹饪，多尝试才能找到最适合自己的配方 😋。

再见啦！下次见！ 👋