标签 http 下的文章

通过实例理解OpenID身份认证

本文永久链接 – https://tonybai.com/2023/12/22/understand-oidc-by-example

在《通过实例理解OAuth2》一文中,我们以实例方式讲解了OAuth2授权码模式(Authorization Code)模式的工作原理。实例中的照片冲印服务经过用户(tonybai)的授权后,使用用户提供的code(实则是由授权服务器分配并通过用户的浏览器重定向到照片冲印服务的)到授权服务器换取了access token,并最终使用access token从云盘系统中读取到了用户的照片信息。

不过,拿到了access token的照片冲印服务并不知道这个access token代表的是云盘服务上的哪个用户,要不是云盘服务在照片list接口返回了用户名(tonybai),照片冲印服务还需要自己为授权给它的用户创建一个临时的用户id标识。当tonybai用户一周后再次访问照片冲印服务时,照片冲印服务还需要再走一次OAuth2授权流程,这对用户的体验并不好。

从照片冲印服务角度来说,它希望在用户第一次使用服务并授权时,就能得到用户身份信息,将用户加入到自己的用户体系中,并通过类似基于会话的身份认证机制在用户后续使用服务时自动识别并认证用户身份。这样,既可以避免用户额外单独注册账号的不佳体验,又可以避免用户下次使用服务时繁琐地授权过程。

然而,尽管OAuth 2.0是一个需要用户交互的安全协议,但它终归不是身份认证协议。但很多像照片冲印服务这样的应用还有通过像云盘系统这一的大厂应用进行用户身份认证的强烈需求,于是有很多厂商都制定了各自专用的标准,比如Facebook、Twitter、LinkedIn和GitHub等,但这些都是专用协议,缺乏标准性,开发者要逐一开发和适配。

于是OpenID基金会基于OAuth2.0制定了OpenID Connect(简称OIDC)这样的开放身份认证协议标准,可以在不同厂商之间通用。

在这篇文章中,我们就来介绍一下基于OpenID的身份认证原理,有了上一篇OAuth2做铺垫,OIDC理解起来就非常容易了。

1. OpenID Connect(OIDC)简介

OpenID Connect是一个开放标准,由OpenID基金会于2014年2月发布。它定义了一种使用OAuth 2.0执行用户身份认证的互通方式。由于该协议的设计具有互通性,一个OpenID客户端应用可以使用同一套协议语言与不同的身份提供者交互,而不需要为每一个身份提供者实现一套有细微差别的协议。OpenID Connect直接基于OAuth 2.0构建,并保持了OAuth2.0的兼容性。现实世界中,在多数情况下,OIDC都会与保护其他API的OAuth基础架构部署在一起。

我们在学习OAuth 2.0时,首先了解了该协议涉及的几个实体,如Client、Authorization Server、Resource Server、Resource owner、Protected resouce等,以及它们的交互流程。知道了这些也就掌握了OAuth2的内核。以此为鉴,我们学习OIDC协议,也从了解都有哪些实体参与了协议交互,以及它们的具体交互流程开始。

OpenID Connect是一个协议套件(OpenID Connect Protocol Suite),涉及Core、Discovery、Dynamic Client Registration等:

不过这里我们仅聚焦OpenID Connect的core 1.0协议规范

就像OAuth2.0支持四种授权模式一样,OIDC基于这四种模式,整合出了三种身份认证类型:

  • Authentication using the Authorization Code Flow
  • Authentication using the Implicit Flow
  • Authentication using the Hybrid Flow

其中Authentication using the Authorization Code Flow这种基于OAuth2授权码流程的身份认证方案应该是使用最为广泛的,本文也将基于这个流程对OIDC进行理解,并赋以实例。

1.1 OIDC协议中的实体与交互流程图

下面是OIDC规范中给出的通用的身份认证流程图,这个图是高度抽象的,适合上面三个flow:

通过这个图,我们先来认识参与OIDC流程中的三个实体:

  • RP(Relying Party)

图的最左端是一个叫RP的实体,如果对应到OAuth2.0那篇文章中的示例,这个RP对应的就是示例中的照片冲印服务,也就是OAuth2.0中的Client,即需要用户(EU)授权的那个实体。

  • OP(OpenID Provider)

OP对应的是OAuth2.0中的Authorization Server+Resource Server,不同的是在OIDC这个特殊场景下,Resource Server中存储的resource就是用户的身份信息

  • EU(End User)

EU,顾名思义就是使用RP服务的用户,它对应OAuth2.0中的Resource Owner。

结合这些实体、上面的抽象流程图以及OAuth2授权码模式的交互图,我画一下OIDC基于授权码模式进行身份认证的实体间的交互图,这里我们依旧以用户使用照片冲印服务为例:

上图就是一个基于授权码流程的OIDC协议流程,是不是赶脚跟OAuth 2.0中的授权码模式的流程几乎完全一致啊!

唯一的区别就是授权服务器(OP)在返回access_token的同时,还多返回了一个ID_TOKEN,我们称这个ID_TOKEN为ID令牌,这个令牌是OIDC身份认证的关键。

1.2 ID_TOKEN的组成

从上图中,我们看到ID_TOKEN与普通的OAuth access_token一起提供给Client(RP)使用,与access_token不同的是,RP是需要对ID_TOKEN进行解析的。那么这个ID_TOKEN究竟是什么呢?在OIDC协议中,ID_TOKEN是一个经过签名的JWT

OIDC协议规范规定了该jwt应该包含的字段信息,包括必选的(REQUIRED)与可选的(OPTIONAL),在这里我们了解下面的必选字段信息即可:

  • iss

令牌的颁发者,其值就是身份认证服务(OP)的URL,比如:http://open.my-yunpan.com:8081/oauth/token,不包含问号作为前缀的查询参数等。

  • sub

令牌的主题标识符,其值是最终用户(EU)在身份认证服务(OP)内部的唯一且永不重新分配的标识符。

  • aud

令牌的目标受众,其值是Client(RP)的标识,必须包含RP的OAuth 2.0客户端ID(client_id),也可以包含其他受众的标识符。

  • exp

过期时间,过期后ID_TOKEN将会失效。其值是一个JSON number,表示从1970-01-01T0:0:0Z开始(以 UTC 度量)到过期日期/时间为止的秒数。

  • iat

认证时间,即版本ID_TOKEN的时间,其值是一个JSON number,表示从1970-01-01T0:0:0Z开始(以 UTC 度量)到认证日期/时间为止的秒数。

注:如果客户端(RP)向身份认证服务器(OP)注册过公钥,则可以使用客户端公钥对该JWT进行非对称签名校验,或者可以使用客户端密钥对该JWT进行对称签名。这种方式可以提高客户端的安全等级,因为可以避免在网络上传递密钥。

在上面图中使用access_token获取user_info的环节中,RP可以通过ID_TOKEN中的sub(EU唯一标识符)到授权服务器的userinfo端点换取用户的基本信息,这样在RP自己的页面上展示EU的标识时就不可以不用9XDF-AABB-001ACFE这样的唯一标识符(sub),而是用TonyBai这样的可理解的字符串了。

注:OpenID Connect使用一个特殊的权限范围值openid来控制对UserInfo端点的访问。OpenID Connect定义了一组标准化的OAuth权限范围,对 应于用户属性的子集,比如profile 、email 、phone 、address等。

了解了OIDC的身份认证流程以及ID_TOKEN的组成后,我们就算对OIDC有个直观的认知了,接下来我们用一个实例来加深一下对OIDC身份认证的理解。

2. OIDC实例

如果你理解了《通过实例理解OAuth2》一文中的实例,那么理解本篇文章中的OIDC实例将是轻而易举的事情。前面说过,OIDC建构在OAuth2之上,与OAuth2兼容,因此,这里的OIDC实例也改自OAuth2一文中的实例。

与OAuth2一文实例相比,OIDC实例中去掉了云盘服务(my-yunpan),仅保留了下面结构:

$tree -L 2 -F oidc-examples
oidc-examples
├── my-photo-print/
│   ├── go.mod
│   ├── go.sum
│   ├── home.html
│   ├── main.go
│   └── profile.html
└── open-my-yunpan/
    ├── go.mod
    ├── go.sum
    ├── main.go
    └── portal.html

其中my-photo-print是照片冲印服务,也是oidc实例中的RP实体,而open-my-yunpan扮演着云盘授权服务,是oidc实例中的OP实体。在编写和运行服务之前,我们同样要先修改一下本机(MacOS或Linux)的/etc/hosts文件:

127.0.0.1 my-photo-print.com
127.0.0.1 open.my-yunpan.com

注:在演示下面步骤前,请先进入到oidc-examples的两个目录下,通过go run main.go启动各个服务程序(每个程序一个终端窗口)。

2.1 用户使用my-photo-print.com照片冲印服务

按照流程,用户首先通过浏览器打开照片冲印服务的首页:http://my-photo-print.com:8080,如下图:

这与OAuth2一文中的实例并无什么差别,该页面也是由my-photo-print/main.go中的homeHandler提供的,它的home.html渲染模板也基本没有变化,因此这里就不赘述了。

当用户选择并点击“使用云盘账号登录”时,浏览器将打开云盘授权服务(OP)的首页(http://open.my-yunpan.com:8081/oauth/portal)。

2.2 使用open.my-yunpan.com进行授权,包括openid权限

云盘授权服务的首页还是“老样子”,唯一的差别就是请求的权限包含了一项openid(有my-photo-print的home.html带过来的):

这个页面同样由open.my-yunpan.com的portalHandler提供,它的逻辑与oauth2的实例相比没有变化,这里也罗列其代码了。

当用户(EU)填写用户名和密码后,点击“授权”,浏览器便会向云盘授权服务的”/oauth/authorize”发起post请求以获取code,负责”/oauth/authorize”端点的authorizeHandler会对用户进行身份认证,通过后,它会分配code并向浏览器返回重定向的应答,重定向的地址就是照片冲印服务的回调地址:http://my-photo-print.com:8080/cb?code=xxx&state=yyy。

2.3 获取access token以及id_token,并用用户唯一标识获取用户基本信息(profile)

这个重定向相当于用户浏览器向http://my-photo-print.com:8080/cb?code=xxx&state=yyy发起请求,为照片冲印服务提供code,该请求由my-photo-print的oauthCallbackHandler处理:

// oidc-examples/my-photo-print/main.go

// callback handler,用户(EU)拿到code后调用该handler
func oauthCallbackHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Println("oauthCallbackHandler:", *r)

    code := r.FormValue("code")
    state := r.FormValue("state")

    // check state
    mu.Lock()
    _, ok := stateCache[state]
    if !ok {
        mu.Unlock()
        fmt.Println("not found state:", state)
        w.WriteHeader(http.StatusBadRequest)
        return
    }
    delete(stateCache, state)
    mu.Unlock()

    // fetch access_token and id_token with code
    accessToken, idToken, err := fetchAccessTokenAndIDToken(code)
    if err != nil {
        fmt.Println("fetch access_token error:", err)
        return
    }
    fmt.Println("fetch access_token ok:", accessToken)

    // parse id_token
    mySigningKey := []byte("iamtonybai")
    claims := jwt.RegisteredClaims{}
    _, err = jwt.ParseWithClaims(idToken, &claims, func(token *jwt.Token) (interface{}, error) {
        return mySigningKey, nil
    })
    if err != nil {
        fmt.Println("parse id_token error:", err)
        return
    }

    // use access_token and userID to get user info
    up, err := getUserInfo(accessToken, claims.Subject)
    if err != nil {
        fmt.Println("get user info error:", err)
        return
    }
    fmt.Println("get user info ok:", up)

    mu.Lock()
    userProfile[claims.Subject] = up
    mu.Unlock()

    // 设置cookie
    cookie := http.Cookie{
        Name:   "my-photo-print.com-session",
        Value:  claims.Subject,
        Domain: "my-photo-print.com",
        Path:   "/profile",
    }
    http.SetCookie(w, &cookie)
    w.Header().Add("Location", "/profile")
    w.WriteHeader(http.StatusFound) // redirect to /profile
}

这个handler中做了很多工作。首先是使用code像授权服务器换取access token和id_token,授权服务器负责颁发token的是tokenHandler:

// oidc-examples/open-yunpan/main.go

func tokenHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Println("tokenHandler:", *r)

    // check client_id and client_secret
    user, password, ok := r.BasicAuth()
    if !ok {
        fmt.Println("no authorization header")
        w.WriteHeader(http.StatusNonAuthoritativeInfo)
        return
    }

    mu.Lock()
    v, ok := validClients[user]
    if !ok {
        fmt.Println("not found user:", user)
        mu.Unlock()
        w.WriteHeader(http.StatusNonAuthoritativeInfo)
        return
    }
    mu.Unlock()

    if v != password {
        fmt.Println("invalid password")
        w.WriteHeader(http.StatusNonAuthoritativeInfo)
        return
    }

    // check code and redirect_uri
    code := r.FormValue("code")
    redirect_uri := r.FormValue("redirect_uri")

    mu.Lock()
    ac, ok := codeCache[code]
    if !ok {
        fmt.Println("not found code:", code)
        mu.Unlock()
        w.WriteHeader(http.StatusNotFound)
        return
    }
    mu.Unlock()

    if ac.redirectURI != redirect_uri {
        fmt.Println("invalid redirect_uri:", redirect_uri)
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    var authResponse struct {
        AccessToken string `json:"access_token"`
        IDToken     string `json:"id_token,omitempty"`
        ExpireIn    int    `json:"expires_in"`
    }

    // generate access_token
    authResponse.AccessToken = randString(16)
    authResponse.ExpireIn = 3600
    now := time.Now()
    expired := now.Add(10 * time.Minute)
    claims := jwt.RegisteredClaims{
        Issuer:    "http://open.my-yunpan.com:8091/oauth/token",
        Subject:   ac.userID,
        Audience:  jwt.ClaimStrings{user}, //client_id
        IssuedAt:  &jwt.NumericDate{now},
        ExpiresAt: &jwt.NumericDate{expired},
    }

    if strings.Contains(ac.scopeTxt, "openid") {
        // generate id_token if contains openid
        mySigningKey := []byte("iamtonybai")
        jwtToken := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
        authResponse.IDToken, _ = jwtToken.SignedString(mySigningKey)
    }

    respData, _ := json.Marshal(&authResponse)
    w.Write(respData)
}

我们看到tokenHandler先是对客户端(client)凭据做了校验,接下来验证code,如果code通过验证,则会分配access_token,并根据scope中是否包含openid决定是否分配id_token,这里我们的权限授权中包含了openid,于是tokenHandler将id_token(一个jwt)一并生成并返回给client。

而拿到access_token和id_token的my-photo-print的oauthCallbackHandler会解析id_token,提取其中的有效信息,比如subject等,并用access_token和id_token中的subject(用户的唯一ID)去授权服务获取用户(EU)的基础身份信息(姓名、主页、邮箱等),并将用户的唯一ID作为cookie存入用户的浏览器。最后让浏览器重定向到my-photo-print的profile页面。

请注意:这里仅是为了简便起见,生产环境请考虑更为安全的会话机制。

profile页面的处理函数为profileHandler:

// oidc-examples/my-photo-print/main.go

// user profile页面
func profileHandler(w http.ResponseWriter, r *http.Request) {
    fmt.Println("profileHandler:", *r)

    cookie, err := r.Cookie("my-photo-print.com-session")
    if err != nil {
        http.Error(w, "找不到cookie,请重新登录", 401)
        return
    }
    fmt.Printf("found cookie: %#v\n", cookie)

    mu.Lock()
    pf, ok := userProfile[cookie.Value]
    if !ok {
        mu.Unlock()
        fmt.Println("not found user:", cookie.Value)
        // 跳转到首页
        http.Redirect(w, r, "/", http.StatusSeeOther)
        return
    }
    mu.Unlock()

    // 渲染照片页面模板
    tmpl := template.Must(template.ParseFiles("profile.html"))
    tmpl.Execute(w, pf)
}

我们看到:该handler首先查找cookie中是否存在用户ID,如果不存在,则重定向到登录页面,如果存在,则取出用户唯一ID,并使用该ID查找用户profile信息,最后展示到web页面上:

到这里,我们看到:这种委托云盘授权服务对my-photo-print的用户进行身份认证并拿到该用户基本信息的机制,就是oidc。

注:一旦拿到云盘授权服务身份认证后的用户信息,RP便可以使用各种身份认证机制来管理EU用户,比如RP可以使用会话管理技术(例如使用会话标识符或浏览器cookie)来跟踪EU的会话状态。如果EU在同一会话期间访问RP应用,RP可以通过会话标识符来识别EU,而无需再次进行身份验证。

3. 小结

通过上面的内容,我们对OpenID Connect(OIDC)有了更直观的理解,这里做一个小结:

  • OIDC是一套身份认证的开放标准协议,基于OAuth 2.0构建,与OAuth 2.0兼容。
  • OIDC协议中主要涉及三个角色:RP(依赖方)、OP(身份提供方)、EU(最终用户)。
  • EU通过RP使用OP进行身份认证后,RP可以获得EU的身份信息。整个流程与OAuth 2.0的授权码流程高度相似。
  • 关键的差别在于:OP返回的token中除了access_token外,还包含一个ID_TOKEN(JWT格式)。
  • RP通过解析ID_TOKEN可以获得EU的唯一标识等信息,并通过access_token进一步获取EU的详细身份信息。
  • RP获得EU身份信息后,可以通过各种机制识别和管理EU,无需EU重复身份验证。

总的来说,OIDC利用OAuth 2.0流程进行身份认证,通过额外返回的ID_TOKEN提供EU身份信息,很好地满足了RP对EU身份管理的需求。

文本涉及的源码可以在这里下载。

4. 参考资料


“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!2023年,Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码,关注代码质量并深入理解Go核心技术,并继续加强与星友的互动。欢迎大家加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) - https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 - https://github.com/bigwhite/gopherdaily

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

Go语言gRPC服务Handler单元测试详解

本文永久链接 – https://tonybai.com/2023/11/25/grpc-handler-unit-testing-in-go

在云原生时代和微服务架构背景下,HTTP和RPC协议成为服务间通信和与客户端交互的两种主要方式。对于Go语言而言,标准库提供了net/http/httptest包,为开发人员提供了便捷的方式来构建服务端HTTP Handler单元测试的测试脚手架代码,而无需真正建立HTTP服务器,让开发人员可以聚焦于对Handler业务逻辑的测试。比如下面这个示例:

// grpc-test-examples/httptest/http_handler_test.go

func myHandler(w http.ResponseWriter, r *http.Request) {
    // 设置响应头
    w.Header().Set("Content-Type", "text/plain")

    // 根据请求方法进行不同的处理
    switch r.Method {
    case http.MethodGet:
        // 处理GET请求
        fmt.Fprint(w, "Hello, World!")
    ... ...
    }
}

func TestMyHandler(t *testing.T) {
    // 创建一个ResponseRecorder来记录Handler的响应
    rr := httptest.NewRecorder()

    // 创建一个模拟的HTTP请求,可以指定请求的方法、路径、正文等
    req, err := http.NewRequest("GET", "/path", nil)
    if err != nil {
        t.Fatal(err)
    }

    // 调用被测试的Handler函数,传入ResponseRecorder和Request对象
    // 这里假设被测试的Handler函数为myHandler
    myHandler(rr, req)

    // 检查响应状态码和内容
    if rr.Code != http.StatusOK {
        t.Errorf("Expected status 200; got %d", rr.Code)
    }
    expected := "Hello, World!"
    if rr.Body.String() != expected {
        t.Errorf("Expected body to be %q; got %q", expected, rr.Body.String())
    }
}

注:对http client端的单元测试,也可以利用httptest的NewServer来构建一个fake的http server

然而,对于使用主流的gRPC等RPC协议的服务端Handler来说,是否存在类似httptest的测试脚手架生成工具包呢?对gRPC的服务端Handler有哪些单元测试的方法呢?在这篇文章中,我们就一起来探究一下。

1. 建立被测的gRPC服务端Handler

我们首先来建立一个涵盖多种gRPC通信模式的服务端Handler集合。

gRPC支持四种通信模式,它们分别为:

  • 简单RPC(Simple RPC,也称为Unary RPC)

这是最简单的,也是最常用的gRPC通信模式,简单来说就是一请求一应答

  • 服务端流RPC(Server-streaming RPC)

客户端发来一个请求,服务端通过流返回多个应答。

  • 客户端流RPC(Client-streaming RPC)

客户端通过流发来多个请求,服务端以一个应答回复。

  • 双向流RPC(Bidirectional-Streaming RPC)

客户端通过流发起多个请求,服务端也通过流对应返回多个应答。

注:关于gRPC四种通信方式的详情,可以参考我之前写的《gRPC客户端的那些事儿》一文。

我们这个SUT(被测目标)是包含以上四种通信模式的gRPC服务,它的Protocol Buffers文件如下:

// grpc-test-examples/grpctest/IDL/proto/mygrpc.proto

syntax = "proto3";

package mygrpc;

service MyService {
  // Unary RPC
  rpc UnaryRPC(RequestMessage) returns (ResponseMessage) {}

  // Server-Streaming RPC
  rpc ServerStreamingRPC(RequestMessage) returns (stream ResponseMessage) {}

  // Client-Streaming RPC
  rpc ClientStreamingRPC(stream RequestMessage) returns (ResponseMessage) {}

  // Bidirectional-Streaming RPC
  rpc BidirectionalStreamingRPC(stream RequestMessage) returns (stream ResponseMessage) {}
}

message RequestMessage {
  string message = 1;
}

message ResponseMessage {
  string message = 1;
}

通过protoc,我们可基于上述proto文件生成MyService桩(Stub)代码,生成的代码放在了mygrpc目录下面:

// grpc-test-examples/grpctest/Makefile

all: gen

gen:
    protoc -I ./IDL/proto mygrpc.proto --gofast_out=plugins=grpc:./mygrpc

注:你的环境下需要安装protocprotoc-gen-go才能正确执行上面生成命令,具体的安装方法可参考protoc安装文档

注:除了使用经典的protoc基于proto文件生成Go源码外,也可以基于Go开发的buf cli进行代码生成和API管理。buf cLi是现代、快速、高效的Protobuf API管理的终极工具,为基于Protobuf的开发和维护提供了全面的解决方案。等有机会的时候,我在以后的文章中详细说说buf。

有了生成的桩代码后,我们便可以建立一个gRPC服务器:

// grpc-test-examples/grpctest/main.go

package main

import (
    pb "demo/mygrpc"
    "log"
    "net"

    "google.golang.org/grpc"
)

func main() {
    // 创建 gRPC 服务器
    lis, err := net.Listen("tcp", ":50051")
    if err != nil {
        log.Fatalf("failed to listen: %v", err)
    }
    s := grpc.NewServer()

    // 注册 MyService 服务
    pb.RegisterMyServiceServer(s, &server{})

    // 启动 gRPC 服务器
    log.Println("Starting gRPC server...")
    if err := s.Serve(lis); err != nil {
        log.Fatalf("failed to serve: %v", err)
    }
}

我们看到:在main函数中,我们创建了一个TCP监听器,并使用grpc.NewServer()创建了一个gRPC服务器。然后,我们通过调用pb.RegisterMyServiceServer()将server类型的实例注册到gRPC服务器上,以处理来自客户端的请求。最后,我们启动gRPC服务器并监听指定的端口。

上面代码中注册到服务器中的server类型就是实现了MyService服务接口的具体类型,它实现了MyService定义的所有方法:

// grpc-test-examples/grpctest/server.go

package main

import (
    "context"
    "fmt"
    "strconv"

    pb "demo/mygrpc"
)

type server struct{}

func (s *server) UnaryRPC(ctx context.Context, req *pb.RequestMessage) (*pb.ResponseMessage, error) {
    message := "Unary RPC received: " + req.Message
    fmt.Println(message)

    return &pb.ResponseMessage{
        Message: "Unary RPC response",
    }, nil
}

func (s *server) ServerStreamingRPC(req *pb.RequestMessage, stream pb.MyService_ServerStreamingRPCServer) error {
    message := "Server Streaming RPC received: " + req.Message
    fmt.Println(message)

    for i := 0; i < 5; i++ {
        response := &pb.ResponseMessage{
            Message: "Server Streaming RPC response " + strconv.Itoa(i+1),
        }
        if err := stream.Send(response); err != nil {
            return err
        }
    }

    return nil
}

func (s *server) ClientStreamingRPC(stream pb.MyService_ClientStreamingRPCServer) error {
    var messages []string

    for {
        req, err := stream.Recv()
        if err != nil {
            return err
        }

        messages = append(messages, req.Message)

        if req.Message == "end" {
            break
        }
    }

    message := "Client Streaming RPC received: " + fmt.Sprintf("%v", messages)
    fmt.Println(message)

    return stream.SendAndClose(&pb.ResponseMessage{
        Message: "Client Streaming RPC response",
    })
}

func (s *server) BidirectionalStreamingRPC(stream pb.MyService_BidirectionalStreamingRPCServer) error {
    for {
        req, err := stream.Recv()
        if err != nil {
            return err
        }

        message := "Bidirectional Streaming RPC received: " + req.Message
        fmt.Println(message)

        response := &pb.ResponseMessage{
            Message: "Bidirectional Streaming RPC response",
        }
        if err := stream.Send(response); err != nil {
            return err
        }
    }
}

在上面代码中,我们创建了一个server结构体类型,并实现了MyService的所有RPC方法。每个方法都接收相应的请求消息,并返回对应的响应消息。我们的目标仅是演示如何对上述gRPC Handler进行单元测试,所以这里的实现逻辑非常简单。

接下来,我们就来逐一对这些gRPC的Handler方法进行单测,我们先从简单的UnaryRPC方法开始。

2. Unary RPC Handler的单元测试

Unary RPC是最简单,也是最容易理解的RPC通信模式,即客户端与服务端采用一请求一应答的模式。server类型的UnaryRPC Handler方法的原型如下:

// grpc-test-examples/grpctest/server.go

func (s *server) UnaryRPC(ctx context.Context, req *pb.RequestMessage) (*pb.ResponseMessage, error)

就像文章开头做的那个httpserver的handler单测一样,我们肯定不想真实启动一个gRPC server,也不想测试gRPC服务器本身。我们只想测试服务端handler方法的逻辑是否正确。

观察一下这个方法原型,我们发现它仅依赖两个消息结构:RequestMessage和ResponseMessage,这两个消息结构是上面基于proto文件自动生成的,这样我们就可以不借助任何工具包实现对UnaryRPC handler方法的单测,也无需启动真实的gRPC Server:

// grpc-test-examples/grpctest/server_test.go

type server struct{}

func TestServerUnaryRPC(t *testing.T) {
    s := &server{}

    req := &pb.RequestMessage{
        Message: "Test message",
    }

    resp, err := s.UnaryRPC(context.Background(), req)
    if err != nil {
        t.Fatalf("UnaryRPC failed: %v", err)
    }

    expectedResp := &pb.ResponseMessage{
        Message: "Unary RPC response",
    }

    if resp.Message != expectedResp.Message {
        t.Errorf("Unexpected response. Got: %s, Want: %s", resp.Message, expectedResp.Message)
    }
}

将其改造为基于subtest和表驱动的测试也非常easy:

// grpc-test-examples/grpctest/server_test.go

func TestServerUnaryRPCs(t *testing.T) {
    tests := []struct {
        name           string
        requestMessage *pb.RequestMessage
        expectedResp   *pb.ResponseMessage
    }{
        {
            name: "Test Case 1",
            requestMessage: &pb.RequestMessage{
                Message: "Test message",
            },
            expectedResp: &pb.ResponseMessage{
                Message: "Unary RPC response",
            },
        },
        // Add more test cases as needed
    }

    s := &server{}

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            resp, err := s.UnaryRPC(context.Background(), tt.requestMessage)
            if err != nil {
                t.Fatalf("UnaryRPC failed: %v", err)
            }

            if resp.Message != tt.expectedResp.Message {
                t.Errorf("Unexpected response. Got: %s, Want: %s", resp.Message, tt.expectedResp.Message)
            }
        })
    }
}

如果gRPC handler测试都像UnaryRPC这样简单那就好了,但实际上…,好吧,我们继续向下看就好了。

3. 针对Streaming通信模式的单元测试

3.1 ServerStreamingRPC的测试

前面说过,gRPC支持三种Streaming通信模式:Server-Streaming RPC、Client-Streaming RPC和Bidirectional-Streaming RPC。

我们先来看看Server-Streaming RPC的方法原型:

// grpc-test-examples/grpctest/server.go
func (s *server) ServerStreamingRPC(req *pb.RequestMessage, stream pb.MyService_ServerStreamingRPCServer) error

我们看到除了RequestMessag外,该方法还依赖一个MyService_ServerStreamingRPCServer的类型,这个类型是一个接口类型:

// grpc-test-examples/mygrpc/mygrpc.pb.go

type MyService_ServerStreamingRPCServer interface {
    Send(*ResponseMessage) error
    grpc.ServerStream
}

到这里,你脑子中可能已经冒出了一个想法:使用fake object来对ServerStreamingRPC进行单测,这的确是一个可行的方法,我们下面就基于这个思路实现一下。

注:关于基于fake object进行单测的内容,大家可以看看我以前写的一篇文章《[]单测时尽量用fake object(https://tonybai.com/2023/04/20/provide-fake-object-for-external-collaborators)》。

3.2 基于fake object的测试

我们首先创建一个实现MyService_ServerStreamingRPCServer的fake object用以代替真实运行RPC服务器时由服务器传入的stream object:

// grpc-test-examples/grpctest/server_with_fakeobject_test.go

import (
    "testing"

    pb "demo/mygrpc"

    "google.golang.org/grpc"
)

type fakeServerStreamingRPCStream struct {
    grpc.ServerStream
    responses []*pb.ResponseMessage
}

func (m *fakeServerStreamingRPCStream) Send(resp *pb.ResponseMessage) error {
    m.responses = append(m.responses, resp)
    return nil
}

我们看到fakeServerStreamingRPCStream的Send方法只是将收到的ResponseMessage追加到且内部的ResponseMessage切片中。

接下来我们为ServerStreamingRPC编写测试用例:

// grpc-test-examples/grpctest/server_with_fakeobject_test.go

func TestServerServerStreamingRPC(t *testing.T) {
    s := &server{}  

    req := &pb.RequestMessage{
        Message: "Test message",
    }  

    stream := &fakeServerStreamingRPCStream{}  

    err := s.ServerStreamingRPC(req, stream)
    if err != nil {
        t.Fatalf("ServerStreamingRPC failed: %v", err)
    }  

    expectedResponses := []string{
        "Server Streaming RPC response 1",
        "Server Streaming RPC response 2",
        "Server Streaming RPC response 3",
        "Server Streaming RPC response 4",
        "Server Streaming RPC response 5",
    }                                                                                                          

    if len(stream.responses) != len(expectedResponses) {
        t.Errorf("Unexpected number of responses. Got: %d, Want: %d", len(stream.responses), len(expectedResponses))
    }                                                                                                          

    for i, resp := range stream.responses {
        if resp.Message != expectedResponses[i] {
            t.Errorf("Unexpected response at index %d. Got: %s, Want: %s", i, resp.Message, expectedResponses[i])
        }
    }
}

在这个测试中,ServerStreamingRPC接收一个请求(req),并通过fake stream object的Send方法返回了5个response,通过与预期的response对比,即可做出测试是否通过的断言。

到这里,我们看到:fake object完全满足对gRPC Server Handler进行测试的要求。不过我们需要针对不同的Handler建立不同的fake object类型,和文初基于httptest创建的测试用例相比,用例间欠缺了一些一致性。

那grpc-go是否提供了类似httptest的工具来帮助我们更一致的实现grpc server handler的测试用例呢?我们继续往下看。

3.3 利用grpc-go提供的测试工具包

grpc-go项目在test下提供了bufconn包,可以帮助我们像httptest那样建立用于测试的“虚拟gRPC服务器”,下面是基于bufconn包建立gRPC测试用服务器的代码:

// grpc-test-examples/grpctest/server_with_buffconn_test.go

package main

import (
    "context"
    "log"
    "net"
    "testing"

    pb "demo/mygrpc"

    "google.golang.org/grpc"
    "google.golang.org/grpc/test/bufconn"
)

func newGRPCServer(t *testing.T) (pb.MyServiceClient, func()) {
    // 创建 bufconn.Listener 作为服务器的监听器
    listener := bufconn.Listen(1024 * 1024)

    // 创建 gRPC 服务器
    srv := grpc.NewServer()

    // 注册服务处理程序
    pb.RegisterMyServiceServer(srv, &server{})

    // 在监听器上启动服务器
    go func() {
        if err := srv.Serve(listener); err != nil {
            t.Fatalf("Server failed to start: %v", err)
        }
    }()

    // 创建 bufconn.Dialer 作为客户端连接
    dialer := func(context.Context, string) (net.Conn, error) {
        return listener.Dial()
    }

    // 使用 DialContext 和 bufconn.Dialer 创建客户端连接
    conn, err := grpc.DialContext(context.Background(), "bufnet", grpc.WithContextDialer(dialer), grpc.WithInsecure())
    if err != nil {
        t.Fatalf("Failed to dial server: %v", err)
    }

    // 创建客户端实例
    client := pb.NewMyServiceClient(conn)
    return client, func() {
        err := listener.Close()
        if err != nil {
            log.Printf("error closing listener: %v", err)
        }
        srv.Stop()
    }
}

newGRPCServer是一个用于在测试中创建gRPC服务器和客户端的辅助函数,它使用bufconn.Listen创建一个bufconn.Listener作为服务器的监听器。bufconn包提供了一种在内存中模拟网络连接的方法。然后,它使用grpc.NewServer()创建了一个新的gRPC服务器实例,并使用pb.RegisterMyServiceServer将待测的服务实例(这里是server类型实例)注册到gRPC服务器中。接下来,它创建了与该服务器建连的gRPC客户端,由于该客户端要与bufconn.Listener建连,这里用了一个dialer函数,该函数将通过调用listener.Dial()来建立与服务器的连接。之后基于该连接,我们创建了MyServiceClient的客户端实例,并返回,供测试用例使用。

基于newGPRCServer这种方式,我们改造一下UnaryRPC的测试用例:

// grpc-test-examples/grpctest/server_with_buffconn_test.go

func TestServerUnaryRPCWithBufConn(t *testing.T) {
    client, shutdown := newGRPCServer(t)
    defer shutdown()

    tests := []struct {
        name           string
        requestMessage *pb.RequestMessage
        expectedResp   *pb.ResponseMessage
    }{
        {
            name: "Test Case 1",
            requestMessage: &pb.RequestMessage{
                Message: "Test message",
            },
            expectedResp: &pb.ResponseMessage{
                Message: "Unary RPC response",
            },
        },
        // Add more test cases as needed
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            resp, err := client.UnaryRPC(context.Background(), tt.requestMessage)
            if err != nil {
                t.Fatalf("UnaryRPC failed: %v", err)
            }

            if resp.Message != tt.expectedResp.Message {
                t.Errorf("Unexpected response. Got: %s, Want: %s", resp.Message, tt.expectedResp.Message)
            }
        })
    }
}

我们看到,相对于前面的TestServerUnaryRPCs,两者复杂度在一个层次。如果结合下面的ServerStreamRPC的测试用例,你就能看出这种方式在测试用例一致性方面的优势了:

// grpc-test-examples/grpctest/server_with_buffconn_test.go

func TestServerServerStreamingRPCWithBufConn(t *testing.T) {
    client, shutdown := newGRPCServer(t)
    defer shutdown()

    req := &pb.RequestMessage{
        Message: "Test message",
    }

    stream, err := client.ServerStreamingRPC(context.Background(), req)
    if err != nil {
        t.Fatalf("ServerStreamingRPC failed: %v", err)
    }

    expectedResponses := []string{
        "Server Streaming RPC response 1",
        "Server Streaming RPC response 2",
        "Server Streaming RPC response 3",
        "Server Streaming RPC response 4",
        "Server Streaming RPC response 5",
    }

    gotResponses := []string{}

    for {
        resp, err := stream.Recv()
        if err != nil {
            break
        }
        gotResponses = append(gotResponses, resp.Message)
    }

    if len(gotResponses) != len(expectedResponses) {
        t.Errorf("Unexpected number of responses. Got: %d, Want: %d", len(gotResponses), len(expectedResponses))
    }

    for i, resp := range gotResponses {
        if resp != expectedResponses[i] {
            t.Errorf("Unexpected response at index %d. Got: %s, Want: %s", i, resp, expectedResponses[i])
        }
    }
}

我们再也无需为每个Server Handler建立各自的fake object了!

由此看到:grpc-go的test/bufconn就是类似httptest的那个grpc server handler的测试脚手架搭建工具。

3.4 其他Streaming模式的Handler测试

有了bufconn这一利器,其他Streaming模式的Handler测试实现逻辑就大同小异了。本文示例中的ClientStreamingRPC和BidirectionalStreamingRPC两个Handler的测试用例就作为作业,交给各位读者去完成吧!

4. 小结

在本文中,我们详细探讨了如何对gRPC服务端Handler进行单元测试,我们的目标是找到像net/http/httptest包那样的,可以为gRPC服务端handler测试提供脚手架代码帮助的测试方法。

我们按照gRPC的四种通信方式,由简到难的逐一探讨各种Handler的单测方法。UnaryRPC handler测试最为简单,毫无技巧的普通测试逻辑便能应付。

但一旦涉及streaming通信方式的测试,我们就需要借助类似fake object的单测技术了。但fake object也有不足,那就是需要为每个RPC handler建立单独的fake object,费时费力还缺少一致性!

好在,grpc-go项目为我们提供了test/bufconn包,该包可以像net/http/httptest包那样帮助我们快速建立可复用的测试脚手架代码,这样我们便可以为所有服务端RPC Handler建立一致、稳定的单元测试用例了!

当然,服务端RPC Handler的单测方法可能不止文中提及这些,各位读者如果有更好的方法和实践,欢迎在评论区留言!

本文涉及的源码可以在这里下载。

5. 参考资料


“Gopher部落”知识星球旨在打造一个精品Go学习和进阶社群!高品质首发Go技术文章,“三天”首发阅读权,每年两期Go语言发展现状分析,每天提前1小时阅读到新鲜的Gopher日报,网课、技术专栏、图书内容前瞻,六小时内必答保证等满足你关于Go语言生态的所有需求!2023年,Gopher部落将进一步聚焦于如何编写雅、地道、可读、可测试的Go代码,关注代码质量并深入理解Go核心技术,并继续加强与星友的互动。欢迎大家加入!

img{512x368}
img{512x368}

img{512x368}
img{512x368}

著名云主机服务厂商DigitalOcean发布最新的主机计划,入门级Droplet配置升级为:1 core CPU、1G内存、25G高速SSD,价格5$/月。有使用DigitalOcean需求的朋友,可以打开这个链接地址:https://m.do.co/c/bff6eed92687 开启你的DO主机之路。

Gopher Daily(Gopher每日新闻) – https://gopherdaily.tonybai.com

我的联系方式:

  • 微博(暂不可用):https://weibo.com/bigwhite20xx
  • 微博2:https://weibo.com/u/6484441286
  • 博客:tonybai.com
  • github: https://github.com/bigwhite
  • Gopher Daily归档 – https://github.com/bigwhite/gopherdaily

商务合作方式:撰稿、出书、培训、在线课程、合伙创业、咨询、广告合作。

如发现本站页面被黑,比如:挂载广告、挖矿等恶意代码,请朋友们及时联系我。十分感谢! Go语言第一课 Go语言精进之路1 Go语言精进之路2 商务合作请联系bigwhite.cn AT aliyun.com

欢迎使用邮件订阅我的博客

输入邮箱订阅本站,只要有新文章发布,就会第一时间发送邮件通知你哦!

这里是 Tony Bai的个人Blog,欢迎访问、订阅和留言! 订阅Feed请点击上面图片

如果您觉得这里的文章对您有帮助,请扫描上方二维码进行捐赠 ,加油后的Tony Bai将会为您呈现更多精彩的文章,谢谢!

如果您希望通过微信捐赠,请用微信客户端扫描下方赞赏码:

如果您希望通过比特币或以太币捐赠,可以扫描下方二维码:

比特币:

以太币:

如果您喜欢通过微信浏览本站内容,可以扫描下方二维码,订阅本站官方微信订阅号“iamtonybai”;点击二维码,可直达本人官方微博主页^_^:
本站Powered by Digital Ocean VPS。
选择Digital Ocean VPS主机,即可获得10美元现金充值,可 免费使用两个月哟! 著名主机提供商Linode 10$优惠码:linode10,在 这里注册即可免费获 得。阿里云推荐码: 1WFZ0V立享9折!


View Tony Bai's profile on LinkedIn
DigitalOcean Referral Badge

文章

评论

  • 正在加载...

分类

标签

归档



View My Stats