4. RESTful API 设计原则：资源命名规范、HTTP方法映射与版本控制策略

在服务目录的 Grafana 告警规则接口设计中，RESTful 风格是构建可维护、可扩展 API 的基石。本章聚焦三个核心设计原则：资源命名规范、HTTP 方法映射以及版本控制策略。遵循这些原则能够确保接口语义清晰、行为可预测，并降低客户端与服务器之间的耦合。

4.1 资源命名规范

RESTful API 的核心是“资源”（Resource）。在告警规则上下文中，资源包括告警规则本身、规则组、通知策略、静默规则等。命名规范应遵循以下准则：

• 使用名词复数形式：资源集合使用复数名词，例如 /api/v1/rules 而非 /api/v1/rule。
• 小写字母与连字符：路径中全部使用小写字母，多单词之间使用连字符（-）分隔，例如 /alert-groups 而非 /alertGroups 或 /alert_groups。
• 层级关系通过路径表达：子资源通过嵌套路径表示，例如 /namespaces/{namespace}/rules 表示某个命名空间下的所有告警规则。
• 避免动词：资源路径中不应出现动词，操作行为由 HTTP 方法表达。例如使用 POST /rules/{id}/activate 而非 POST /rules/activate-rule。

4.2 HTTP 方法映射

每个 HTTP 方法对应一种标准操作，映射到资源的 CRUD（创建、读取、更新、删除）行为。在告警规则 API 中，方法映射应严格遵循语义一致性。

4.3 版本控制策略

API 版本控制是保障向后兼容性的关键手段。在服务目录中，告警规则接口的版本控制推荐采用 URI 路径版本号 策略，即版本号直接嵌入在 URL 路径中。

4.3.1 版本控制方式对比

4.3.2 版本生命周期管理

版本控制不仅仅是 URL 设计，还涉及版本的生命周期管理。以下是推荐的版本演进流程：

1. v1 发布：初始版本，提供核心告警规则 CRUD 接口。
2. v2 开发：在 v1 稳定运行后，开始 v2 的设计与开发，v2 可以引入新的字段、修改请求/响应结构。
3. v2 发布：v2 上线后，v1 进入“维护模式”，仅修复安全漏洞和严重缺陷。
4. v1 废弃：在 v2 发布至少 6 个月后，宣布 v1 废弃，并在响应头中添加 Deprecation: true 和 Sunset: <date> 字段。
5. v1 下线：在废弃至少 3 个月后，v1 正式下线，返回 410 Gone 状态码。

4.3.3 版本控制示例代码

以下是一个基于 Go 语言的版本路由示例，展示如何同时支持 v1 和 v2 的告警规则接口：

package main

import (
    "net/http"
)

func main() {
    mux := http.NewServeMux()

    // v1 路由
    v1 := http.NewServeMux()
    v1.HandleFunc("GET /api/v1/rules", listRulesV1)
    v1.HandleFunc("POST /api/v1/rules", createRuleV1)
    v1.HandleFunc("GET /api/v1/rules/{id}", getRuleV1)
    v1.HandleFunc("PUT /api/v1/rules/{id}", updateRuleV1)
    v1.HandleFunc("DELETE /api/v1/rules/{id}", deleteRuleV1)

    // v2 路由（新增字段和优化响应）
    v2 := http.NewServeMux()
    v2.HandleFunc("GET /api/v2/rules", listRulesV2)
    v2.HandleFunc("POST /api/v2/rules", createRuleV2)
    v2.HandleFunc("GET /api/v2/rules/{id}", getRuleV2)
    v2.HandleFunc("PUT /api/v2/rules/{id}", updateRuleV2)
    v2.HandleFunc("DELETE /api/v2/rules/{id}", deleteRuleV2)

    // 版本中间件：添加版本响应头
    mux.Handle("/api/v1/", versionMiddleware("1", v1))
    mux.Handle("/api/v2/", versionMiddleware("2", v2))

    http.ListenAndServe(":8080", mux)
}

func versionMiddleware(version string, next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        w.Header().Set("X-API-Version", version)
        next.ServeHTTP(w, r)
    })
}

// 占位函数实现
func listRulesV1(w http.ResponseWriter, r *http.Request)  { /* v1 实现 */ }
func createRuleV1(w http.ResponseWriter, r *http.Request) { /* v1 实现 */ }
func getRuleV1(w http.ResponseWriter, r *http.Request)    { /* v1 实现 */ }
func updateRuleV1(w http.ResponseWriter, r *http.Request) { /* v1 实现 */ }
func deleteRuleV1(w http.ResponseWriter, r *http.Request) { /* v1 实现 */ }

func listRulesV2(w http.ResponseWriter, r *http.Request)  { /* v2 实现 */ }
func createRuleV2(w http.ResponseWriter, r *http.Request) { /* v2 实现 */ }
func getRuleV2(w http.ResponseWriter, r *http.Request)    { /* v2 实现 */ }
func updateRuleV2(w http.ResponseWriter, r *http.Request) { /* v2 实现 */ }
func deleteRuleV2(w http.ResponseWriter, r *http.Request) { /* v2 实现 */ }

4.4 综合设计示例

将上述三个原则整合到服务目录的告警规则接口设计中，形成以下完整的接口清单：