REST API设计模式和反模式

RESTful API已经成为构建现代网络应用的事实标准。它们允许一个灵活和可扩展的架构,可以很容易地被广泛的客户端所消费。然而,设计一个既健壮又可维护的REST API是很有挑战性的,特别是对于刚入行的开发者。

在这篇文章中,我们将探讨一些常见的REST API设计模式和开发者应该注意的反模式。我们还将提供Golang和Open API Schema的代码片段来帮助说明这些概念。

REST API设计模式

1.以资源为导向的架构(ROA)

面向资源的架构(ROA)是一种设计模式,强调资源在RESTful API中的重要性。资源是RESTful API的关键构件,它们应该被设计成易于消费和操作的方式。

在Golang中实现ROA的一种方式是使用gorilla/mux包进行路由。这里有一个例子:

go 复制代码
r := mux.NewRouter()
r.HandleFunc("/users/{id}", getUser).Methods("GET")
r.HandleFunc("/users", createUser).Methods("POST")
r.HandleFunc("/users/{id}", updateUser).Methods("PUT")
r.HandleFunc("/users/{id}", deleteUser).Methods("DELETE")

在Open API Schema中,你可以使用path参数来定义资源。下面是一个例子:

go 复制代码
paths:
 /users/{id}:
 get:
 ...
 put:
 ...
 delete:
 ...
 /users:
 post:
 ...

2. HATEOAS

超媒体作为应用状态的引擎(HATEOAS)是一种设计模式,允许客户动态地浏览RESTful API。API提供超媒体链接,客户可以按照这些链接来发现资源并与之互动。

为了在GoLang中实现HATEOAS,你可以使用go-jsonapi包。这里有一个例子:

go 复制代码
type User struct {
 ID string `json:"id"`
 Name string `json:"name"`
 Links *Links `json:"links,omitempty"`
}

type Links struct {
 Self *Link `json:"self,omitempty"`
}

type Link struct {
 Href string `json:"href,omitempty"`
}

func getUser(w http.ResponseWriter, r *http.Request) {
 userID := mux.Vars(r)["id"]
 user := User{ID: userID, Name: "John Doe"}
 user.Links = &Links{
 Self: &Link{Href: fmt.Sprintf("/users/%s", userID)},
 }
 jsonapi.MarshalOnePayload(w, &user)
}

在Open API Schema中,你可以使用links参数来定义超媒体链接。这里有一个例子:

go 复制代码
paths:
 /users/{id}:
 get:
 responses:
 '200':
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/User'
 links:
 self:
 href: '/users/{id}'

REST API反模式

1.RPC式的API

远程过程调用(RPC)风格的API是RESTful API设计中一个常见的反模式。RPC风格的API暴露了直接映射到底层实现的方法,而不是专注于资源。

下面是一个GoLang中RPC风格API的例子:

go 复制代码
func getUser(w http.ResponseWriter, r *http.Request) {
 userID := r.FormValue("id")
 user := userService.GetUser(userID)
 json.NewEncoder(w).Encode(user)
}

在Open API Schema中,你可以使用operationId参数来定义RPC风格的API。下面是一个例子:

go 复制代码
paths:
 /users:
 get:
 operationId: getUser

2.过度的工程设计

过度工程是RESTful API设计中另一个常见的反模式。当开发者试图预测每一个可能的用例并建立一个复杂的API来适应它们时,就会出现过度设计。

这里有一个Golang中过度工程的例子:

go 复制代码
func getUser(w http.ResponseWriter, r *http.Request) {
 userID := mux.Vars(r)["id"]
 user, err := userService.GetUser(userID)
 if err != nil {
 handleError(w, err)
 return
 }
 json.NewEncoder(w).Encode(user)
}

func createUser(w http.ResponseWriter, r *http.Request) {
 var user User
 err := json.NewDecoder(r.Body).Decode(&user)
 if err != nil {
 handleError(w, err)
 return
 }
 user.ID = uuid.New().String()
 user.CreatedAt = time.Now()
 user.UpdatedAt = time.Now()
 err = userService.CreateUser(user)
 if err != nil {
 handleError(w, err)
 return
 }
 json.NewEncoder(w).Encode(user)
}

func updateUser(w http.ResponseWriter, r *http.Request) {
 userID := mux.Vars(r)["id"]
 var user User
 err := json.NewDecoder(r.Body).Decode(&user)
 if err != nil {
 handleError(w, err)
 return
 }
 user.ID = userID
 user.UpdatedAt = time.Now()
 err = userService.UpdateUser(user)
 if err != nil {
 handleError(w, err)
 return
 }
 json.NewEncoder(w).Encode(user)
}

func deleteUser(w http.ResponseWriter, r *http.Request) {
 userID := mux.Vars(r)["id"]
 err := userService.DeleteUser(userID)
 if err != nil {
 handleError(w, err)
 return
 }
 w.WriteHeader(http.StatusNoContent)
}

func handleError(w http.ResponseWriter, err error) {
 w.WriteHeader(http.StatusInternalServerError)
 fmt.Fprint(w, err. Error())
}

在Open API Schema中,你可以使用x-go-genie扩展定义过度工程。这里有一个例子:

go 复制代码
paths:
 /users/{id}:
   get:
     x-go-genie:
       serviceName: UserService
       methodName: GetUser
   put:
     x-go-genie:
       serviceName: UserService
       methodName: UpdateUser
   delete:
     x-go-genie:
       serviceName: UserService
       methodName: DeleteUser
 /users:
   post:
     x-go-genie:
       serviceName: UserService
       methodName: CreateUser

总结

设计一个既健壮又可维护的RESTful API可能具有挑战性,但通过遵循最佳实践并避免常见的反模式,开发人员可以创建易于消费和操作的API。在这篇文章中,我们探讨了一些常见的REST API设计模式和反模式,并提供了GoLang和Open API Schema的代码片段来帮助说明这些概念。

相关推荐
小沈同学呀5 小时前
创建一个Spring Boot Starter风格的Basic认证SDK
java·spring boot·后端
方圆想当图灵7 小时前
如何让百万 QPS 下的服务更高效?
分布式·后端
凤山老林7 小时前
SpringBoot 轻量级一站式日志可视化与JVM监控
jvm·spring boot·后端
凡梦千华7 小时前
Django时区感知
后端·python·django
Chan168 小时前
JVM从入门到实战:从字节码组成、类生命周期到双亲委派及打破双亲委派机制
java·jvm·spring boot·后端·intellij-idea
烈风9 小时前
004 Rust控制台打印输出
开发语言·后端·rust
用户21411832636029 小时前
用 AI 一键搞定!中医药科普短视频制作升级版
后端
秋难降10 小时前
零基础学习SQL(十一):SQL 索引结构|从 B+Tree 到 Hash,面试常问的 “为啥选 B+Tree” 有答案了
数据库·后端·mysql
SamDeepThinking10 小时前
用设计模式重构核心业务代码的一次实战
java·后端·设计模式