RESTfulAPI开发全解析

# RESTful API 开发全解析 ## 1. API 结构选项 B 在之前的结构中，我们为每个资源在单个目录下创建了四个文件。而在选项 B 中，我们会创建四个目录：controllers、routes、repositories 和 services。在每个目录下，会根据类别数量创建子目录，且每个子目录中为每个资源创建一个文件。 ## 2. 资源方法 REST 并不强制使用特定协议，但目前 HTTP 方法在 REST 协议中占据主导地位。以下是常见 HTTP 方法及其用途： | 方法 | 用途 | 示例 | 缓存特性 | | ---- | ---- | ---- | ---- | | GET | 仅用于检索信息，不改变状态，代表读操作 | GET https://www.example.com/accounts <br> GET https://www.example.com/accounts/search?name=john <br> GET https://www.example.com/accounts?page=5 | 默认可缓存，有长度限制 | | POST | 为特定资源创建新数据，可创建单行或多行 | POST https://www.example.com/accounts <br> POST https://www.example.com/accounts/myaccount_id/users | 默认不可缓存，无长度限制，数据通常在请求体中 | | PUT | 通常用于更新现有资源状态，也可创建新数据，具有幂等性 | PUT https://www.example.com/accounts/{myaccount_id} | 不可缓存 | | DELETE | 用于删除特定资源 | | 不可缓存 | | 其他 | PATCH、OPTIONS、HEAD、CONNECT 和 TRACE 等，但使用频率不如上述方法 | | | ### 2.1 HTTP 状态码 以下是标准 HTTP 状态码的简要概述： | 状态码范围 | 含义 | 常见状态码及说明 | | ---- | ---- | ---- | | 1XX | 信息响应，不常用 | | | 2XX | 成功响应 | 200 OK：GET 方法常用，表明数据检索成功 <br> 201 Create：POST/PUT 常用 | | 3XX | 重定向消息，用于将请求重定向到其他服务器、端点、域名等 | | | 4XX | 客户端错误响应，请求有问题，由客户端负责 | 400 Bad Request：客户端提供信息不正确 <br> 401 Unauthorized：服务器无法识别客户端 <br> 403 Forbidden：客户端已识别但无法访问请求数据 <br> 404 Not Found：请求未被识别 | | 5XX | 服务器错误响应，服务器自身有问题 | 500 Internal server error：服务器遇到未知情况 | ## 3. 构建服务器 ### 3.1 Gin Gonic 配置 Gin 是一个 HTTP 网络框架。以下是使用 Go 和 Gin 创建 RESTful API 服务器的基本步骤： 1. **main.go 文件**： ```go func main() { port := 8080 engine := internal.BuildEngine() srv := &http.Server{ Addr: fmt.Sprintf(":%d", port), Handler: engine, } log.Printf("Starting server on port %d", port) if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed { log.Print("error while running API gin server", "error", err.Error()) os.Exit(1) } } ``` 2. **BuildEngine 函数**： ```go func BuildEngine() *gin.Engine { engine := gin.New() engine.Use(gin.Logger()) engine.Use(gin.Recovery()) engine.Use(CORS()) group := engine.Group("/api") RegisterRoutes(group) // engine.use(<any middleware you want>) return engine } ``` 3. **RegisterRoutes 函数**： ```go func RegisterRoutes(routerGroup *gin.RouterGroup) { apple.RegisterRoutes(routerGroup) } ``` 4. **routes.go 文件**： ```go package apple import "github.com/gin-gonic/gin" var Path = "/fruits/apple" func RegisterRoutes(group *gin.RouterGroup) { group.GET(Path, gin.HandlersChain{ProcessRequest}...) } ``` 5. **controller.go 文件**： ```go package apple import "github.com/gin-gonic/gin" func ProcessRequest(c *gin.Context) { c.JSON(200, gin.H{ "color": "red", "date": "2023-12-11", "taste": "sweet", }) } ``` ## 4. 责任链模式 责任链模式是一种将多个命令链接起来，使一个命令引发另一个命令的设计模式。该模式通过中间件实现，有助于满足分层系统的约束。我们可以在不同层面应用中间件： - 在 `BuildEngine` 函数中为整个 API 应用相关中间件。 - 在 `RegisterRoutes` 函数中为特定组（类别）应用中间件。 - 在 `routes.go` 中为资源级别应用特定中间件。 ## 5. CORS CORS（Cross-Origin Resource Sharing）是一种浏览器安全特性，用于限制不必要的 HTTP 请求。以下是创建 Gin 中间件处理 CORS 的代码： ```go func CORS() gin.HandlerFunc { return func(c *gin.Context) { c.Writer.Header().Set("Access-Control-Allow-Origin", "*") c.Writer.Header().Set("Access-Control-Allow-Credentials", "true") c.Writer.Header().Set("Access-Control-Allow-Methods", "POST, GET") c.Next() } } ``` ## 6. API 能力 每个 API 都需要支持源自产品需求的能力。以下是一些常见的 API 能力： ### 6.1 分页 分页是将内容分成不同页面或部分的过程，常用于导航或处理大量数据。常见的分页算法有： -