微信号:Golangweb

介绍:欢迎来到 Go语言社区 社区网址:www.golangweb.com APP网址:app.golangweb.com 社区非公司性质,完全个人爱好建立;做的不好的地方大家见谅.

Go语言开发RESTFul JSON API

2018-05-17 22:46 WalkerQiao

RESTful API在Web项目开发中广泛使用,本文针对Go语言如何一步步实现RESTful JSON API进行讲解, 另外也会涉及到RESTful设计方面的话题。

也许我们之前有使用过各种各样的API, 当我们遇到设计很糟糕的API的时候,简直感觉崩溃至极。希望通过本文之后,能对设计良好的RESTful API有一个初步认识。

JSON API是什么?

JSON之前,很多网站都通过XML进行数据交换。如果在使用过XML之后,再接触JSON, 毫无疑问,你会觉得世界多么美好。这里不深入JSON API的介绍,有兴趣可以参考jsonapi。

基本的Web服务器

从根本上讲,RESTful服务首先是Web服务。 因此我们可以先看看Go语言中基本的Web服务器是如何实现的。下面例子实现了一个简单的Web服务器,对于任何请求,服务器都响应请求的URL回去。

 1package main
2import (
3    "fmt"
4    "html"
5    "log"
6    "net/http"
7)
8func main() {
9    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
10        fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
11    })
12    log.Fatal(http.ListenAndServe(":8080", nil))
13}

上面基本的web服务器使用Go标准库的两个基本函数HandleFunc和ListenAndServe。

1func HandleFunc(pattern string, handler func(ResponseWriter, *Request)) {
2    DefaultServeMux.HandleFunc(pattern, handler)
3}
4func ListenAndServe(addr string, handler Handler) error {
5    server := &Server{Addr: addr, Handler: handler}
6    return server.ListenAndServe()
7}

运行上面的基本web服务,就可以直接通过浏览器访问http://localhost:8080来访问。

1> go run basic_server.go

添加路由

虽然标准库包含有router, 但是我发现很多人对它的工作原理感觉很困惑。 我在自己的项目中使用过各种不同的第三方router库。 最值得一提的是Gorilla Web ToolKit的mux router。

另外一个流行的router是来自Julien Schmidt的叫做httprouter的包。

 1package main
2import (
3    "fmt"
4    "html"
5    "log"
6    "net/http"
7    "github.com/gorilla/mux"
8)
9func main() {
10    router := mux.NewRouter().StrictSlash(true)
11    router.HandleFunc("/", Index)
12    log.Fatal(http.ListenAndServe(":8080", router))
13}
14func Index(w http.ResponseWriter, r *http.Request) {
15    fmt.Fprintf(w, "Hello, %q", html.EscapeString(r.URL.Path))
16}

要运行上面的代码,首先使用go get获取mux router的源代码:

1> go get github.com/gorilla/mux

上面代码创建了一个基本的路由器,给请求"/"赋予Index处理器,当客户端请求http://localhost:8080/的时候,就会执行Index处理器。

如果你足够细心,你会发现之前的基本web服务访问http://localhost:8080/abc能正常响应: 'Hello, "/abc"', 但是在添加了路由之后,就只能访问http://localhost:8080了。 原因很简单,因为我们只添加了对"/"的解析,其他的路由都是无效路由,因此都是404。

创建一些基本的路由

既然我们加入了路由,那么我们就可以再添加更多路由进来了。

假设我们要创建一个基本的ToDo应用, 于是我们的代码就变成下面这样:

 1package main
2import (
3    "fmt"
4    "log"
5    "net/http"
6    "github.com/gorilla/mux"
7)
8func main() {
9    router := mux.NewRouter().StrictSlash(true)
10    router.HandleFunc("/", Index)
11    router.HandleFunc("/todos", TodoIndex)
12    router.HandleFunc("/todos/{todoId}", TodoShow)
13    log.Fatal(http.ListenAndServe(":8080", router))
14}
15func Index(w http.ResponseWriter, r *http.Request) {
16    fmt.Fprintln(w, "Welcome!")
17}
18func TodoIndex(w http.ResponseWriter, r *http.Request) {
19    fmt.Fprintln(w, "Todo Index!")
20}
21func TodoShow(w http.ResponseWriter, r *http.Request) {
22    vars := mux.Vars(r)
23    todoId := vars["todoId"]
24    fmt.Fprintln(w, "Todo Show:", todoId)
25}

在这里我们添加了另外两个路由: todos和todos/{todoId}。

这就是RESTful API设计的开始。

请注意最后一个路由我们给路由后面添加了一个变量叫做todoId。

这样就允许我们传递id给路由,并且能使用具体的记录来响应请求。

基本模型

路由现在已经就绪,是时候创建Model了,可以用model发送和检索数据。在Go语言中,model可以使用结构体来实现,而其他语言中model一般都是使用类来实现。

 1package main
2import (
3    "time"
4)
5type Todo struct {
6    Name      string
7    Completed bool
8    Due       time.Time
9}
10type Todos []Todo

上面我们定义了一个Todo结构体,用于表示待做项。 另外我们还定义了一种类型Todos, 它表示待做列表,是一个数组,或者说是一个分片。

稍后你就会看到这样会变得非常有用。

返回一些JSON

我们有了基本的模型,那么我们可以模拟一些真实的响应了。我们可以为TodoIndex模拟一些静态的数据列表。

 1package main
2import (
3    "encoding/json"
4    "fmt"
5    "log"
6    "net/http"
7    "github.com/gorilla/mux"
8)
9// ...
10func TodoIndex(w http.ResponseWriter, r *http.Request) {
11    todos := Todos{
12        Todo{Name: "Write presentation"},
13        Todo{Name: "Host meetup"},
14    }
15    json.NewEncoder(w).Encode(todos)
16}
17// ...

现在我们创建了一个静态的Todos分片来响应客户端请求。注意,如果你请求http://localhost:8080/todos, 就会得到下面的响应:

 1[
2    {
3        "Name": "Write presentation",
4        "Completed": false,
5        "Due": "0001-01-01T00:00:00Z"
6    },
7    {
8        "Name": "Host meetup",
9        "Completed": false,
10        "Due": "0001-01-01T00:00:00Z"
11    }
12]

更好的Model

对于经验丰富的老兵来说,你可能已经发现了一个问题。响应JSON的每个key都是首字母答写的,虽然看起来微不足道,但是响应JSON的key首字母大写不是习惯的做法。 那么下面教你如何解决这个问题:

1type Todo struct {
2    Name      string    `json:"name"`
3    Completed bool      `json:"completed"`
4    Due       time.Time `json:"due"`
5}

其实很简单,就是在结构体中添加标签属性, 这样可以完全控制结构体如何编排(marshalled)成JSON。

拆分代码

到目前为止,我们所有代码都在一个文件中。显得杂乱, 是时候拆分代码了。我们可以将代码按照功能拆分成下面多个文件。

我们准备创建下面的文件,然后将相应代码移到具体的代码文件中:

  • main.go: 程序入口文件。

  • handlers.go: 路由相关的处理器。

  • routes.go: 路由。

  • todo.go: todo相关的代码。

 1package main
2import (
3    "encoding/json"
4    "fmt"
5    "net/http"
6    "github.com/gorilla/mux"
7)
8func Index(w http.ResponseWriter, r *http.Request) {
9    fmt.Fprintln(w, "Welcome!")
10}
11func TodoIndex(w http.ResponseWriter, r *http.Request) {
12    todos := Todos{
13        Todo{Name: "Write presentation"},
14        Todo{Name: "Host meetup"},
15    }
16    if err := json.NewEncoder(w).Encode(todos); err != nil {
17        panic(err)
18    }
19}
20func TodoShow(w http.ResponseWriter, r *http.Request) {
21    vars := mux.Vars(r)
22    todoId := vars["todoId"]
23    fmt.Fprintln(w, "Todo show:", todoId)
24}


 1package main
2import (
3    "net/http"
4    "github.com/gorilla/mux"
5)
6type Route struct {
7    Name        string
8    Method      string
9    Pattern     string
10    HandlerFunc http.HandlerFunc
11}
12type Routes []Route
13func NewRouter() *mux.Router {
14    router := mux.NewRouter().StrictSlash(true)
15    for _, route := range routes {
16        router.
17            Methods(route.Method).
18            Path(route.Pattern).
19            Name(route.Name).
20            Handler(route.HandlerFunc)
21    }
22    return router
23}
24var routes = Routes{
25    Route{
26        "Index",
27        "GET",
28        "/",
29        Index,
30    },
31    Route{
32        "TodoIndex",
33        "GET",
34        "/todos",
35        TodoIndex,
36    },
37    Route{
38        "TodoShow",
39        "GET",
40        "/todos/{todoId}",
41        TodoShow,
42    },
43}


1package main
2import "time"
3type Todo struct {
4    Name      string    `json:"name"`
5    Completed bool      `json:"completed"`
6    Due       time.Time `json:"due"`
7}
8type Todos []Todo
9}


1package main
2import (
3    "log"
4    "net/http"
5)
6func main() {
7    router := NewRouter()
8    log.Fatal(http.ListenAndServe(":8080", router))
9}


更好的Routing

我们重构的过程中,我们创建了一个更多功能的routes文件。 这个新文件利用了一个包含多个关于路由信息的结构体。 注意,这里我们可以指定请求的类型,例如GET, POST, DELETE等等。

输出Web日志

在拆分的路由文件中,我也包含有一个不可告人的动机。稍后你就会看到,拆分之后很容易使用另外的函数来修饰http处理器。

首先我们需要有对web请求打日志的能力,就像很多流行web服务器那样的。 在Go语言中,标准库里边没有web日志包或功能, 因此我们需要自己创建。

 1package logger
2import (
3    "log"
4    "net/http"
5    "time"
6)
7func Logger(inner http.Handler, name string) http.Handler {
8    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
9        start := time.Now()
10        inner.ServeHTTP(w, r)
11        log.Printf(
12            "%s\t%s\t%s\t%s",
13            r.Method,
14            r.RequestURI,
15            name,
16            time.Since(start),
17        )
18    })
19}

上面我们定义了一个Logger函数,可以给handler进行包装修饰。

这是Go语言中非常标准的惯用方式。其实也是函数式编程的惯用方式。 非常有效,我们只需要将Handler传入该函数, 然后它会将传入的handler包装一下,添加web日志和耗时统计功能。

应用Logger修饰器

要应用Logger修饰符, 我们可以创建router, 我们只需要简单的将我们所有的当前路由都包到其中, NewRouter函数修改如下:

 1func NewRouter() *mux.Router {
2    router := mux.NewRouter().StrictSlash(true)
3    for _, route := range routes {
4        var handler http.Handler
5        handler = route.HandlerFunc
6        handler = Logger(handler, route.Name)
7        router.
8            Methods(route.Method).
9            Path(route.Pattern).
10            Name(route.Name).
11            Handler(handler)
12    }
13    return router
14}

现在再次运行我们的程序,我们就可以看到日志大概如下:

2014/11/19 12:41:39 GET /todos TodoIndex 148.324us

这个路由文件太疯狂...让我们重构它吧

路由routes文件现在已经变得稍微大了些, 下面我们将它分解成多个文件:

  • routes.go

  • router.go

 1package main
2import "net/http"
3type Route struct {
4    Name        string
5    Method      string
6    Pattern     string
7    HandlerFunc http.HandlerFunc
8}
9type Routes []Route
10var routes = Routes{
11    Route{
12        "Index",
13        "GET",
14        "/",
15        Index,
16    },
17    Route{
18        "TodoIndex",
19        "GET",
20        "/todos",
21        TodoIndex,
22    },
23    Route{
24        "TodoShow",
25        "GET",
26        "/todos/{todoId}",
27        TodoShow,
28    },
29}


 1package main
2import (
3    "net/http"
4    "github.com/gorilla/mux"
5)
6func NewRouter() *mux.Router {
7    router := mux.NewRouter().StrictSlash(true)
8    for _, route := range routes {
9        var handler http.Handler
10        handler = route.HandlerFunc
11        handler = Logger(handler, route.Name)
12        router.
13            Methods(route.Method).
14            Path(route.Pattern).
15            Name(route.Name).
16            Handler(handler)
17    }
18    return router
19}

另外再承担一些责任

到目前为止,我们已经有了一些相当好的样板代码(boilerplate), 是时候重新审视我们的处理器了。我们需要稍微多的责任。 首先修改TodoIndex,添加下面两行代码:

 1func TodoIndex(w http.ResponseWriter, r *http.Request) {
2    todos := Todos{
3        Todo{Name: "Write presentation"},
4        Todo{Name: "Host meetup"},
5    }
6    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
7    w.WriteHeader(http.StatusOK)
8    if err := json.NewEncoder(w).Encode(todos); err != nil {
9        panic(err)
10    }
11}

这里发生了两件事。 首先,我们设置了响应类型并告诉客户端期望接受JSON。第二,我们明确的设置了响应状态码。

Go语言的net/http服务器会尝试为我们猜测输出内容类型(然而并不是每次都准确的), 但是既然我们已经确切的知道响应类型,我们总是应该自己设置它。

稍等片刻,我们的数据库在哪里?

很明显,如果我们要创建RESTful API, 我们需要一些用于存储和检索数据的地方。然而,这个是不是本文的范围之内, 因此我们将简单的创建一个非常简陋的模拟数据库(非线程安全的)。

我们创建一个repo.go文件,内容如下:

 1package main
2import "fmt"
3var currentId int
4var todos Todos
5// Give us some seed data
6func init() {
7    RepoCreateTodo(Todo{Name: "Write presentation"})
8    RepoCreateTodo(Todo{Name: "Host meetup"})
9}
10func RepoFindTodo(id int) Todo {
11    for _, t := range todos {
12        if t.Id == id {
13            return t
14        }
15    }
16    // return empty Todo if not found
17    return Todo{}
18}
19func RepoCreateTodo(t Todo) Todo {
20    currentId += 1
21    t.Id = currentId
22    todos = append(todos, t)
23    return t
24}
25func RepoDestroyTodo(id int) error {
26    for i, t := range todos {
27        if t.Id == id {
28            todos = append(todos[:i], todos[i+1:]...)
29            return nil
30        }
31    }
32    return fmt.Errorf("Could not find Todo with id of %d to delete", id)
33}

给Todo添加ID

我们创建了模拟数据库,我们使用并赋予id, 因此我们相应的也需要更新我们的Todo结构体。

1package main
2import "time"
3type Todo struct {
4    Id        int       `json:"id"`
5    Name      string    `json:"name"`
6    Completed bool      `json:"completed"`
7    Due       time.Time `json:"due"`
8}
9type Todos []Todo

更新我们的TodoIndex

要使用数据库,我们需要在TodoIndex中检索数据。修改代码如下:

1func TodoIndex(w http.ResponseWriter, r *http.Request) {
2    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
3    w.WriteHeader(http.StatusOK)
4    if err := json.NewEncoder(w).Encode(todos); err != nil {
5        panic(err)
6    }
7}

POST JSON

到目前为止,我们只是输出JSON, 现在是时候进入存储一些JSON了。

在routes.go文件中添加如下路由:

1Route{
2    "TodoCreate",
3    "POST",
4    "/todos",
5    TodoCreate,
6},

Create路由

 1func TodoCreate(w http.ResponseWriter, r *http.Request) {
2    var todo Todo
3    body, err := ioutil.ReadAll(io.LimitReader(r.Body, 1048576))
4    if err != nil {
5        panic(err)
6    }
7    if err := r.Body.Close(); err != nil {
8        panic(err)
9    }
10    if err := json.Unmarshal(body, &todo); err != nil {
11        w.Header().Set("Content-Type", "application/json; charset=UTF-8")
12        w.WriteHeader(422) // unprocessable entity
13        if err := json.NewEncoder(w).Encode(err); err != nil {
14            panic(err)
15        }
16    }
17    t := RepoCreateTodo(todo)
18    w.Header().Set("Content-Type", "application/json; charset=UTF-8")
19    w.WriteHeader(http.StatusCreated)
20    if err := json.NewEncoder(w).Encode(t); err != nil {
21        panic(err)
22    }
23}

首先我们打开请求的body。 注意我们使用io.LimitReader。这样是保护服务器免受恶意攻击的好方法。假设如果有人想要给你服务器发送500GB的JSON怎么办?

我们读取body以后,我们解构Todo结构体。 如果失败,我们作出正确的响应,使用恰当的响应码422, 但是我们依然使用json响应回去。 这样可以允许客户端理解有错发生了, 而且有办法知道到底发生了什么错误。

最后,如果所有都通过了,我们就响应201状态码,表示请求创建的实体已经成功创建了。 我们同样还是响应回代表我们创建的实体的json, 它会包含一个id, 客户端可能接下来需要用到它。

POST一些JSON

我们现在有了伪repo, 也有了create路由,那么我们需要post一些数据。 我们使用curl通过下面的命令来达到这个目的:

1curl -H "Content-Type: application/json" -d '{"name": "New Todo"}' http://localhost:8080/todos

如果你再次通过http://localhost:8080/todos访问,大概会得到下面的响应:

 1[
2    {
3        "id": 1,
4        "name": "Write presentation",
5        "completed": false,
6        "due": "0001-01-01T00:00:00Z"
7    },
8    {
9        "id": 2,
10        "name": "Host meetup",
11        "completed": false,
12        "due": "0001-01-01T00:00:00Z"
13    },
14    {
15        "id": 3,
16        "name": "New Todo",
17        "completed": false,
18        "due": "0001-01-01T00:00:00Z"
19    }
20]

我们还没有做的事情

虽然我们已经有了很好的开端,但是还有很多事情没有做:

  • 版本控制: 如果我们需要修改API, 结果完全改变了怎么办? 可能我们需要在我们的路由开头加上/v1/prefix?

  • 授权: 除非这些都是公开/免费API, 我们可能还需要授权。 建议学习JSON web tokens的东西。

eTag - 如果你正在构建一些需要扩展的东西,你可能需要实现eTag。

还有什么?

对于所有项目来说,开始都很小,但是很快就变得失控了。但是如果我们想要将它带到另外一个层次, 让他生产就绪, 还有一些额外的事情需要做:

  • 大量重构(refactoring).

  • 为这些文件创建几个包,例如一些JSON助手、修饰符、处理器等等。

  • 测试, 使得,你不能忘记这点。这里我们没有做任何测试。对于生产系统来说,测试是必须的。

源代码

https://github.com/corylanou/...

总结

对我来说,最重要的,需要记住的是我们要建立一个负责任的API。 发送适当的状态码,header等,这些是API广泛采用的关键。我希望本文能让你尽快开始自己的API。

参考链接

  • Go语言RESTful JSON API实现

  • JSON API

  • Gorilla Web Toolkit

  • httprouter

  • JSON Web Tokens

  • eTag

  • 专题首页


版权申明:内容来源网络,版权归原创者所有。除非无法确认,我们都会标明作者及出处,如有侵权烦请告知,我们会立即删除并表示歉意。谢谢。



Golang语言社区

ID:Golangweb

游戏服务器架构丨分布式技术丨大数据丨游戏算法学习


 
Golang语言社区 更多文章 gRPC服务发现&负载均衡 Knapsack problem algorithms for my real Github go语言项目stars数排行榜 LollipopGo实战小组--leaf并发压力测试文档 Dynamic Nginx Router... in Go!
猜您喜欢 如何实现 C/C++ 与 Python 的通信? perl模块推荐21—UserAgent模拟HTTP上传文件 从20世纪开始的科技大佬预言,哪些落空哪些成真了? Druid大数据架构线下技术交流