4. RESTful API 设计原则：资源命名、HTTP动词使用、状态码选择、版本控制策略

在构建基于Go的任务调度平台OpenAPI时，RESTful设计原则是接口可维护性与可扩展性的基石。本章围绕资源命名、HTTP动词、状态码与版本控制四个核心维度展开，确保API符合业界最佳实践，同时适配任务调度场景的特殊需求。

4.1 资源命名：名词复数、层级清晰、语义自描述

RESTful API将一切视为资源，URL路径仅使用名词（复数形式），避免动词。任务调度平台的核心资源包括任务、执行记录、调度策略、队列等。

4.2 HTTP动词：精确映射CRUD与任务调度操作

标准CRUD操作使用GET/POST/PUT/DELETE，任务调度平台还需支持“触发执行”“暂停”“恢复”等动作。这些动作应设计为子资源上的POST，而非自定义动词。

4.3 状态码选择：精确表达接口结果

状态码是API响应语义的核心载体。任务调度平台需覆盖成功、客户端错误、服务端错误三大类，避免一律返回200或500。

4.4 版本控制策略：URL路径优先，兼容演进

API版本控制是保障向后兼容的关键。任务调度平台推荐使用URL路径版本控制（/api/v1/），兼顾直观性与路由灵活性。

4.5 Go代码示例：基于gin的RESTful路由与版本分组

package router

import (
    "github.com/gin-gonic/gin"
    "task-scheduler/api/v1/handler"
    "task-scheduler/api/v1/middleware"
)

func SetupRouter() *gin.Engine {
    r := gin.Default()

    // v1 版本路由组
    v1 := r.Group("/api/v1")
    {
        // 任务资源
        tasks := v1.Group("/tasks")
        {
            tasks.GET("", handler.ListTasks)           // GET /api/v1/tasks
            tasks.POST("", handler.CreateTask)         // POST /api/v1/tasks
            tasks.GET("/:taskId", handler.GetTask)     // GET /api/v1/tasks/{taskId}
            tasks.PUT("/:taskId", handler.UpdateTask)  // PUT /api/v1/tasks/{taskId}
            tasks.DELETE("/:taskId", handler.DeleteTask) // DELETE /api/v1/tasks/{taskId}

            // 动作子资源
            tasks.POST("/:taskId/executions", handler.TriggerExecution)
            tasks.POST("/:taskId/pause", handler.PauseTask)
            tasks.POST("/:taskId/resume", handler.ResumeTask)
        }

        // 调度策略资源
        schedules := v1.Group("/schedules")
        {
            schedules.GET("", handler.ListSchedules)
            schedules.POST("", handler.CreateSchedule)
            schedules.GET("/:schId", handler.GetSchedule)
            schedules.PUT("/:schId", handler.UpdateSchedule)
            schedules.DELETE("/:schId", handler.DeleteSchedule)
        }
    }

    // 健康检查（无版本）
    r.GET("/health", handler.HealthCheck)

    return r
}