2023年十二月月 发布的文章

有效表达软件架构的最小图集

本文永久链接 – https://tonybai.com/2023/12/06/a-minimum-set-of-diagrams-for-expressing-software-architecture

无论你是专职的软件架构师,还是在团队内兼职充当软件架构师角色的开发人员,一旦你处在软件架构师这个位置上,你自然就会遇到软件架构设计的三个困惑:

  • 如何更深刻地理解业务;
  • 如何更正确地取舍(包括技术性和业务性的);
  • 如何更有效地表达软件架构。

以上每个困惑展开来写都够写一本书的。而在这篇文章中,我仅聚焦最后一个困惑,聊聊我心目中表达软件架构的有效方式 — 最小图集(Minimum Diagram Set)。

1. 为什么软件架构需要有效表达

众所周知,软件架构承载着系统关键的技术决策和业务约束,指导着复杂软件的构建与演进,是实现软件系统的蓝图。但并不是说有了好的软件架构就一定可以做出好的软件系统,软件系统最终还是要经由开发人员来实现

如果说架构师是软件架构的生产者,那么开发人员可以理解为是软件架构的消费者。但和一件普通商品一样,往往消费者很难Get到产品设计者的全部idea,产品越复杂,消费者Get到的比例越低,于是商品的生产者就会绞尽脑汁地制作产品说明书、功能演示视频等,目的就是想从不同角度更多、更有效的表达自己的商品的特性。对于普通商品而言,消费者Get程度低顶多是少用几个功能特性;但对于架构师生产的“产品”:架构设计成果而言,如果其消费者开发人员Get的程度低,那影响就会很严重,甚至可能会导致软件系统的开发彻底失败。

并且更不幸的是:我们的软件系统都是“复杂产品”。这样,如何表达和解读软件架构,弥合生产者与消费者之间的Gap,让开发者更多更深刻的理解软件架构这件“产品”便成为了架构师的困惑,日常架构设计工作中的难题,也是业界探索的重要课题。

架构设计是架构师与开发者之间的协议,只有有效的、充分的表达,协议才能被共识理解和忠实执行。业界在有效表达软件架构这条路上摸索了很多年,下面简单说说架构设计表达的演进历程。

2. 软件架构表达方式演进简史

软件架构表达的目的就是要直观地传达架构设计人员的思想和意图,使开发团队可以达成对架构设计的一致理解,促进各个团队协作,并作为开发人员编写代码以及管理人员推进项目的重要指导与参考。

2.1 自然语言描述

在软件工程的早期阶段,软件架构设计通常使用自然语言(如英语)进行描述。架构师会使用文档、规范和书面记录来表达架构设计的概念、原则、结构、组件和交互。然而,自然语言描述存在歧义性、解释性不足、理解起来较慢的问题,可能导致误解和沟通障碍。

2.2 图形化表达

人类大脑中传输的信息90%是视觉信息,其处理图形的速度要比处理文字的速度快上万倍。于是随着软件架构的复杂性增加,人们开始采用更直观、更易理解的图形化方法来描述架构设计(并辅以自然语言的文字描述)。

提到图形化表达,最简单的方法就是使用一支笔+一张白纸,基于自己“创造”的符号绘制草图(Sketch,以下草图来自c4model.com):

这种非规范的框线草图虽然提供了灵活性,但付出的代价却是一致性,因为大家都在创造自己的制图符号,而不是使用统一的标准。

2.3 结构化的图形表达

结构化图是在设计表达迈向标准化方面走出的重要一步。结构化图包括数据流图、控制流图、层次图、组件图等,用于可视化表示系统的组件、模块、依赖关系和交互流程等(下图中元素来自维基百科)。

作为一种可以直观可视化描述与沟通架构设计的方式,结构化图形成为了表达架构设计的常见方法之一。不过,早期结构化表达的类型有限,无法涵盖所有环节,有的也没有形成标准,为了提高标准化程度,满足架构设计表达的全部需求,人们在二十世纪末推出了大一统的图形化建模语言UML。

2.4 统一建模语言(UML)

统一建模语言(Unified Modeling Language,UML)是一种通用的标准化、图形化建模语言,广泛用于软件架构和设计的表示,在软件架构表达方法方面具有里程碑意义:

UML第一次在规范层面对图形表示进行了标准化,它提供了一组规范化的图形符号,用于描述系统的结构、行为和交互。在那个Rational统一过程(RUP)以及面向对象设计方法如日中天的时代,人们每每进行设计时,言必称使用UML。UML在图形化、标准化表达设计图方面走到了至今为止都无人企及的高峰。

但是,20多年后的今天,UML并没有成为当时标准出品方期望的那个样子,没能成为表达软件系统设计的主流符号系统。也许是它的复杂性阻碍了有效沟通,让人们看到它的spec后就“望而却步”了。不过UML并没有死掉,它依然活着,UML规范中的一些图(Diagram)依然被大家常用,比如:序列图(Sequence Diagram)用例图(Use Case Diagram)类图(Class Diagram)等。

2.5 形式化表达

业界在寻求图形化表达标准化的同时,也有一个分支在寻求用自然语言的“标准化”表达方法,这就是软件架构设计的形式化表达,在这个领域形成的语言被称为架构描述语言(ADL)。ADL提供了一组特定的语法和语义规则,用于定义系统的组件、接口、依赖关系、行为和性能特征。ADL使架构师能够使用精确的语言来表达和分析架构设计,支持自动化的验证和分析工具,在学术研究这个小众领域还是很有受众的。不过,显然在大多数工程化淋雨,形式化表达门槛太高,对于软件架构在团队内快速有效建立共识起不到什么作用。

下面是一些ADL的实现,感兴趣的童鞋可以了解一下:

2.6 多视角的表达

有了UML这个前车之鉴后,人们似乎也放弃了在图记号“标准化”之路上的继续探索了,而是回归问题本源:怎么有效,就怎么来

在工程实践中,人们认清了一个事实:很难在一张大图(Diagram)中进行软件架构设计的有效表达。于是大家开始采用“盲人摸象”的策略,将一个架构按不同视角表达为不同的图(Diagram),这样当开发人员将多个视角形成的图都理解后,也就理解了整个架构设计

按照这个多视角表达的思路(也被称为是一种软件架构建模思路),业界先后出现了:

逻辑视图(Logical View)关注系统的功能和功能模块,描述系统中各个模块之间的关系、接口和行为。它展示了系统的静态结构和动态行为,以及模块之间的通信和信息流。

进程视图(Process View)描述系统的并发和分布式特性,关注系统中的进程、线程、任务以及它们之间的关系和通信。该视图展示了系统的并发性、性能、可伸缩性等方面。

物理视图(Physical View)描述系统在硬件和软件环境中的部署和分布情况,包括物理设备、网络拓扑、软件组件的部署位置等。它关注系统的部署架构、可靠性、安全性等方面。

开发视图(Development View)关注系统的软件开发过程和组织结构,描述软件模块的组织、构建、测试和部署过程。它展示了软件开发团队的组织结构、开发工具、版本控制等方面。

场景视图(Scenario View)描述系统在特定使用情境下的行为和交互,以用户场景、用例或故事来说明系统的功能和行为。它帮助验证和验证系统架构的正确性和适应性。

C4模型是一种简洁、易于理解的软件架构建模方法,由Simon Brown提出。它通过四个层次的视图来描述软件系统的不同方面,包括语境视图(Context Diagram,这里借鉴了《程序员必读之软件架构》)一书中对Context的翻译)、容器视图(Container Diagram)、组件视图(Component Diagram)和代码视图(Code Diagram),如下图所示:

语境视图是最高层级的视图,用于描述软件系统与外部实体之间的关系和交互。它展示了系统所处的环境和与外部实体(如用户、其他系统、第三方服务等)的关系,以及它们之间的交互方式。

容器视图关注系统内部的软件容器及其之间的关系和交互。容器可以是物理的、虚拟的或逻辑的,它们承载着系统中的组件或服务。容器可以是应用程序、数据库、消息队列、Web服务等。容器视图描述了系统的主要部件,以及它们之间的依赖关系和通信方式。

组件视图进一步展开容器视图中的组件,描述系统内部的组件及其之间的关系和交互。组件视图展示了系统的模块、类、库或其他可重用的软件单元,并显示它们之间的依赖关系、接口和通信方式。

代码视图是最底层的视图,关注具体的代码实现细节。它用于描述系统中的类、函数、方法等代码单元的结构、关系和实现细节。代码视图可以是面向对象的类图、模块图或其他代码组织结构的表示方式,用于帮助开发人员理解和浏览源代码。

下面示意图可以更直观的展示出语境、容器、组件以及代码之间这种逐渐“展开”的层次关系:

通过C4模型的这四个层次的视图,架构师可以逐渐深入地描述和表达软件系统的不同层次和组成部分,从整体到细节,帮助团队成员和利益相关者更好地理解和沟通软件架构。

Arc42是一种用于软件架构文档化的模板和方法,它提供了一套规范和指导原则来描述软件系统的架构。下面是Arc42的全景图:

我们看到:Arc42模板也包含了多个视图,每个视图都关注系统架构的不同方面,包括Context、Building Block View、Runtime View以及Deployment View等。

Context View:描述系统与其外部环境之间的关系和交互,强调边界的概念,分为技术Context与业务Context。

部署视图(Deployment View)描述了系统的部署架构和环境,包括物理设备、服务器、网络拓扑以及协议等信息。

构件视图(Building Block View)描述了系统内部的组件、模块、子系统、包等,并展示它们之间的关系和依赖。构件视图是源码结构的概览。

运行时视图(Runtime View)描述了系统在运行时的行为和交互以及具体场景下对其他构件的运行时依赖。使用序列图、状态图等方式可展示系统的运行时行为。

2.7 Diagrams As Code

架构设计不是一成不变的,需要不断演进,因此架构视图也需要“与时俱进”的更新。但直接更新图片格式似乎很不方便,也无法在形式上很好的达成一致,于是一些基于DSL语法生成架构设计图(Diagram)的工具便涌现了出来,比如:PlantUMLStructurizrMermaid等。有了这些工具,架构师便可以使用文本编辑器来“画图”,支持“所见即所得”。并且由于Diagrams As Code(代码即图),我们可以将架构设计图与版本控制系统很好地集成。

到这里,我们知道了基于多视角+“Diagrams As Code”是目前的主流的架构设计表达和实践方法,那么我们在软件架构表达实践中,究竟选择哪几个视角来表达呢?这个目前没有统一标准。调研了4+1 Views、C4 model以及Arc42后,我这里说说自己日常做架构表达时使用的最小视图集。

3. 最小图集

很多读者可能听说或学习过或实践过金字塔写作,金字塔写作原理是一种用于新闻报道和科技写作的写作方法,它的核心思想是将最重要的信息放在文章的开头,然后逐渐向下展开,提供更多的细节和背景信息。

金字塔写作的优势在于:

  • 它可以迅速吸引读者的注意力,让读者在最短时间内了解文章的核心内容;
  • 它还可确保信息传递:将最重要的信息放在开头,可以避免读者在阅读过程中错过关键信息或迷失在细枝末节中,确保信息有效地传达给读者;
  • 它还具备灵活性和可定制性,不要求严格按照一个固定的结构来组织文章,而是提供了一种基本的思路和原则,可以根据具体情况进行调整和定制,以适应不同的写作需求和读者群体。

我理解,金字塔写作方法之所以能够成功,其本质是站在了读者的角度去思考问题,想读者之所想,做读者之所需。

软件架构表达的目的也是让开发人员快速深入的理解架构,与设计人员达成共识,指导后续软件系统的实现。所以要想形成有效表达,我们就需要像金字塔写作那样站在开发人员的角度来考虑架构表达,借鉴金字塔原理,自上而下,先表达最重要的信息,然后逐渐向下展开,避免开发人员在理解过程中错过关键信息或迷失在细枝末节当中。

综合前面介绍的多种Views的方法,我们觉得软件架构表达的起点,即第一个图必须是语境图(Context Diagram)。

3.1 语境图(Context Diagram)

语境图表达的是系统最高的抽象层次,是最高视角,全局视角。通过语境图,可以解决开发人员在内心中提出的下面问题:

  • 我们构建的(或已经构建的)软件系统是什么(What)?
  • 谁会用它?
  • 如何融入已有的IT环境?
  • 系统的边界是什么?(业务的,技术的)

语境图不会也不应该展示太多细节,它是软件系统设计图的起点。后续的图都是用“放大镜”将我们的系统放大后的细节的表达。当牵涉到理解系统间接口的问题时,语境图还可以为你识别可能需要沟通的人提供了一个起点。

语境图向开发者展现的重点在于软件系统的范围以及与外部的交互行为(用户< – >系统、系统< – >系统等等)。下面是使用structurizr绘制的一个语境图的实例:

语境图中心蓝色的矩形框代表的是我们的软件系统,上方的user、role、actor是我们的软件系统的用户;client是与我们的软件系统交互的系统,是系统到系统交互的一个代表;在我们的软件系统、Inner System1和Inner System2之外有一个虚线框,代表了企业范围;而Inner System1和Inner System2是我们的软件系统在企业内部依赖的系统;同时,我们的软件系统还依赖企业外部的Outer System1和Outer System2。

上述语境图对应的structurizr dsl代码如下:

// system context diagrams

workspace {

    model {
        u = person "User"
        r = person "Role"
        a = person "Actor"
        c = softwareSystem "Client Software System" {
            tags "client"
        }

        enterprise = group "Enterprise A" {
            s = softwareSystem "Our Software System" {
                tags "server"
            }

            d1 = softwareSystem "Inner System1" {
                tags "dep"
            }

            d2 = softwareSystem "Inner System2" {
                tags "dep"
            }
        }
        d3 = softwareSystem "Outer System1" {
            tags "dep"
        }

        d4 = softwareSystem "Outer System2" {
            tags "dep"
        }

        u -> s "Uses"
        r -> s "Uses"
        a -> s "Uses"
        c -> s "Call"
        s -> d1 "Uses"
        s -> d2 "Uses"
        s -> d3 "Uses"
        s -> d4 "Uses"
    }

    views {
        systemContext s {
            include *
            autoLayout
        }

        styles {
            element "server" {
                background #1168bd
                color #ffffff
            }

            element "dep" {
                background #e5e4e2
                color #000000
            }

            element "client" {
                background #e5e4e2
                color #000000
            }

            element "Person" {
                shape person
                background #08427b
                color #ffffff
            }
        }

    }

}

基于语境图,就好比我们站在万米高空一览Our Software System。不过对于架构设计表达来说,这还不够,现在是时候下降高度让视野进入到系统内部去挖掘一些细节了。

3.2 容器图(Container Diagram)

在从万米高空的系统全局视角了解了我们的软件系统是什么后,我们将第一次进入到系统内部。我们现在所处的高度是100米,在这个高度上,可以清晰地看到软件系统的整体形态、内部脉络、技术选择、职责分布以及各个部分之间是如何交流的。我们将每个部分称为一个容器(container)。一个容器通常可以表示一个应用/服务或数据存储,如果你的软件系统采用了微服务架构,那么将每个服务作为一个容器通常是可行的。

针对每个容器,我们可以设置它的属性:名字(如Web App、API网关、关系数据库存储、订阅服务等)、实现技术(如mvc等)以及功能性的描述。在容器间的联系上我们可以附加上通信方式(json over http、gRPC、websocket等)。

下面是上面语境图中的My Software System的容器图:

在这个容器图中,我们看到了系统支持通过Web app和mobile app访问和使用;系统的入口使用了API网关;系统内部分为业务服务和基础服务,基础服务封装了到关系数据库、对象存储(oss)的接口(关系数据库和oss都是技术选择);业务服务可以调用企业内部服务,亦可调用企业外部服务,并且明确了调用方式。

下面是生成上述容器图的structurizr的代码:

// container diagrams

workspace {

    model {
        u = person "User"

        enterprise = group "Enterprise A" {
            s = softwareSystem "Our Software System" {
                tags "server"

                mobileApp = container "Mobile App" {
                    tags "container"
                }

                webApp = container "Web App" {
                     tags "container"
                }

                apiGw = container "API Gateway" {
                     tags "container"
                }

                biz1 = container "Business Service 1" {
                     tags "container"
                }

                biz2 = container "Business Service 2" {
                     tags "container"
                }

                biz3 = container "Business Service 3" {
                     tags "container"
                }

                base1 = container "Base Service 1" {
                     tags "container"
                }

                base2 = container "Base Service 2" {
                     tags "container"
                }

                base3 = container "Base Service 3" {
                     tags "container"
                }

                rds = container "Relational Database system" {
                     tags "container"
                }

                oss = container "Object Storage Service" {
                     tags "container"
                }
            }

            d1 = softwareSystem "Inner System1" {
                tags "dep"
            }

            d2 = softwareSystem "Inner System2" {
                tags "dep"
            }
        }

        d3 = softwareSystem "Outer System1" {
            tags "dep"
        }

        d4 = softwareSystem "Outer System2" {
            tags "dep"
        }

        u -> mobileApp "Uses"
        u -> webApp "Uses"
        mobileApp -> apiGw "Makes API calls to" "JSON/HTTPS"
        WEBApp -> apiGw "Makes API calls to" "JSON/HTTPS"
        apiGw -> biz1 "Route API calls to" "gRPC"
        apiGw -> biz2 "Route API calls to" "gRPC"
        apiGw -> biz3 "Route API calls to" "gRPC"
        biz1 -> base1 "Inner API calls to" "gRPC"
        biz1 -> base2 "Inner API calls to" "gRPC"
        biz2 -> base2 "Inner API calls to" "gRPC"
        biz2 -> base3 "Inner API calls to" "gRPC"
        biz3 -> base3 "Inner API calls to" "gRPC"
        base1 -> rds "Reads from and writes to" "Raw SQL"
        base1 -> oss "Reads from and writes to" "HTTPS"
        base2 -> rds "Reads from and writes to" "Raw SQL"
        base3 -> oss "Reads from and writes to" "HTTPS"
        biz1 -> d1 "Make API calls to" "HTTP"
        biz2 -> d3 "Make API calls to" "HTTP"
        biz3 -> d2 "Make API calls to" "HTTP"
        biz3 -> d4 "Make API calls to" "HTTP"
    }

    views {
        container s {
            include *
            autoLayout
        }

        styles {
            element "server" {
                background #1168bd
                color #ffffff
            }

            element "container" {
                background #1168bd
                color #ffffff
            }

            element "dep" {
                background #e5e4e2
                color #000000
            }

            element "Person" {
                shape person
                background #08427b
                color #ffffff
            }
        }

    }

}

注:在容器图这个层次上,group关键字没有起作用,导致企业内部服务与外部服务放在一起了。

按照C4 model的思路,接下来我们会再下降高度,来到10米的高空,进入到某个容器的内部。但容器内部的设计在我看来属于详细设计范畴,如果采用的是微服务架构,那么容器内部的设计就相当于某个服务的设计。所以这里,我并未将这部分作为架构表达的必需之图。

3.3 序列图(Sequence Diagram)

无论是语境图,还是容器图,从大类来看,都属于静态的结构图。但做过软件系统设计和研发的童鞋都知道,仅有静态的表达还是不够的,不足以传达软件系统的所有信息,我们还需要对动态行为的表达。这就是为什么我将序列图作为软件表达最小图集一份子的原因。

可能有些人将序列图作为需求分析阶段的产物,其实,序列图既可以在需求阶段产生,也可以在架构设计阶段产生。它在不同阶段有不同的应用和目的。

在需求阶段,序列图被用于描述系统的功能需求和行为。它可以帮助分析和定义系统的用例或用户故事,以及系统与外部实体(如用户、其他系统、服务等)之间的交互过程。通过序列图,需求分析人员和开发团队可以更清晰地理解系统的功能需求,并就用户与系统之间的交互进行沟通和确认。

在架构设计阶段,序列图被用于描述系统的结构和组件之间的交互。在这个阶段,序列图通常用于展示系统的运行时行为、组件之间的消息传递和调用关系。架构师使用序列图来验证系统的设计方案,确保系统的各个组件按预期互相协作,并满足功能和性能要求。

这里的序列图,可以对应前面的Arc42的Runtime View,以及C4 model的Dynamic Diagram

序列图也是UML语言中最常被使用的一种Diagram,即便是在UML不那么被提及的今天,我个人也推荐使用UML的序列图来表达,而不推荐用structurizr来画了,structurizr在序列图方面的表达能力还是弱了许多。

你可以用你最喜欢的画图工具来绘制UML序列图(比如我经常用的drawio),也可以选择plantuml这种基于DSL语法生成序列图的方式来绘制。plantuml对序列图的支持还是非常好的,支持了序列图的大多数元素,可以绘制出非常复杂的图来(下图来自plantuml官网):

针对一个复杂的软件系统,我们可能需要针对不同的Container(或更进一步的组件)绘制较多的序列图,至少要覆盖到软件系统各个Container的核心交互流程。

3.4 部署图(Deployment Diagram)

无论是C4模型,还是arc42,亦或是UML语言,都包含部署图。在软件架构表达时,准确表达部署设计,对开发人员后续的实现具有很好的指导作用。通过部署图,架构设计人员可以说明静态图中的软件系统和/或容器实例是如何部署到给定部署环境(如生产、暂存、开发等)中的基础设施上的,比如下面这个部署示意图(来自c4model.com):

我们看到部署图中的核心角色是部署节点(Node),它代表了软件系统/容器实例运行的位置;可能是物理基础设施(如物理服务器或设备)、虚拟化基础设施(如IaaS、PaaS、虚拟机)、容器化基础设施(如Docker容器)、执行环境(如数据库服务器、Java EE Web/应用服务器、Microsoft IIS)等,并且部署节点还可以嵌套。此外,右下角的”x N”表示需要多少个部署节点。

通过部署图还可以表达云基础架构的情况(下图来自c4model.com),可以包含DNS、负载均衡器以及防火墙等部署的基础设施的节点:

structurizr对于部署图支持的还不错,还可以像上图那样使用不同公有云提供商特色的Theme来绘制部署图。

到这里,我们已经“凑齐”了表达软件系统架构的最小图集:语境图、容器图、序列图和部署图。我们要学会灵活使用这些图。在软件系统十分复杂的情况下,我们可以将语境图分为System Landscape diagram和多个sub system的语境图,之后以此类推,对于每个sub system做容器图等。

4. 最小图集之外的图(可选)

有些公司或组织会将架构设计阶段延伸到container内部,这样对软件系统架构的表达就要延伸到详细设计,甚至是编码阶段时,我们就要考虑下面两个类型的Diagram了:组件图和代码图。

4.1 组件图(Component Diagram)

如果容器图阶段,你所在的高度是100米,那么组件图阶段,你将位于高度为10米的空中,这足以让你看清容器中每个组件(Component)的细节。

组件图就是容器内部的设计,它涉及到容器内部各个逻辑组件的结构与组件间的交互。在这个层次,你可以使用你擅长的面向对象设计方法,或者面向契约/接口的设计模式,你也可以使用一些成熟的企业应用设计模式,比如MVC等。

下面是一张组件图示例(来自c4model.com):

我们看到中间的部分就是API Application这个容器内部的逻辑组件结构与交互情况。有些时候在组件图这一层面,我们甚至可以对照初对应项目中的代码布局结构。

对于组件图中关键组件间的复杂交互流程,可辅以序列图的方式来表达。

此外,组件图可以使用structurizr绘制,语法和语境图、容器图十分相似。

4.2 代码图(Code Diagram)

再下降,我们来到离地面1米的高度,我们几乎要躬身入局,参与编码了。通常架构设计不会到达这个阶段,架构师们在100米或10米高度完成任务后,就可以去休息了。

但如果包含这个阶段,我们要给出的便是代码图(Code Diagram),再直白些,就是UML类图、E-R关系图等,下面是一个示意图:

这是一个直面开发人员的图,你可以看到编程语言中的那些机制:接口、继承、实现等等,开发人员甚至可以通过工具将这样的uml class图直接转换为项目的骨架代码。

4. 小结

本文首先介绍了为什么软件架构需要有效表达,以便开发者更好地理解架构设计。然后回顾了软件架构表达方式的演进历史,从自然语言描述到图形化表达,再到结构化图形表达、UML、形式化表达,最终发展到现在的多视角表达方式。

文章结合笔者实践经验,借鉴多个多视角软件架构模型,提出了最小图集的概念,笔者认为有效表达软件架构最关键的视角有四个,分别是:

  1. 语境图:描述系统的整体位置和边界
  2. 容器图:展示系统内部的容器及其关系
  3. 序列图:呈现容器内组件以及组件之间的交互行为
  4. 部署图:阐明系统在实际环境中的部署情况

此外,我认为还可根据需要补充组件图和代码图等更细节的视图。这套最小图集能较全面地表达软件系统的静态结构和动态行为,帮助开发者理解架构设计。

总的来说,该文章从工程实践的视角出发,提出了一套行之有效的软件架构表达方法,对于架构设计的团队沟通及实现具有很好的指导意义。

btw,在容器图或组件图设计阶段,如果要完善工程设计,还可以结合具体的接口文档予以表达,比如基于Swagger的API设计文档等。

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

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

通过实例理解API网关的主要功能特性

本文永久链接 – https://tonybai.com/2023/12/03/understand-api-gateway-main-functional-features-by-example

在当今的技术领域中,“下云”的概念正逐渐抬头,像David Heinemeier Hansson(37signals公司的联合创始人, Ruby on Rails的Creator)就直接将公司所有的业务都从公有云搬迁到了自建的数据中心中。虽说大多数企业不会这么“极端”,但随着企业对云原生架构采用的广泛与深入,不可避免地面临着对云服务的依赖。云服务在过去的几年中被广泛应用于构建灵活、可扩展的应用程序和基础设施,为企业提供了许多便利和创新机会。然而,随着业务规模的增长和数据量的增加,云服务的成本也随之上升。企业开始意识到,对云服务的依赖已经成为一个值得重新评估的议题。云服务的开销可能占据了企业可用的预算的相当大部分。为了保持竞争力并更好地控制成本,企业需要寻找方法来减少对云服务的依赖,寻找更经济的解决方案,同时确保仍能获得所需的性能、安全性和可扩展性。

在这样的背景下,我们的关注点是选择一款适宜的API网关,从主流功能特性的角度来评估候选者的支持。API网关作为现代云原生应用架构中的关键组件,扮演着连接前端应用和后端服务的中间层,负责管理、控制和保护API的访问。它的功能特性对于确保API的安全性、可靠性和可扩展性至关重要。

尽管API网关并不是一个新鲜事物了,但对于那些长期依赖于云供应商的服务的人来说,它似乎变得有些“陌生”。因此,本文旨在帮助我们重新理解API网关的主要特性,并获得对API网关选型的能力,以便在停止使用云供应商服务之前,找到一个合适的替代品^_^。

1. API网关回顾

API网关是现代应用架构中的关键组件之一,它的存在简化了应用程序的架构,并为客户端提供一个单一的访问入口,并进行相关的控制、优化和管理。API网关可以帮助企业实现微服务架构、提高系统的可扩展性和安全性,并提供更好的开发者体验和用户体验。

1.1 API网关的演化

随着互联网的快速发展和企业对API的需求不断增长,API网关作为一种关键的中间层技术逐渐崭露头角并经历了一系列的演进和发展。这里将API网关的演进历史粗略分为以下几个阶段:

  • API网关之前的早期阶段

在互联网发展的早期阶段,大多数应用程序都是以单体应用的形式存在。后来随着应用规模的扩大和业务复杂性的增加,单体应用的架构变得不够灵活和可扩展,面向服务架构(Service-Oriented Architecture,SOA)逐渐兴起,企业开始将应用程序拆分成一组独立的服务。这个时期,每个服务都是独立对外暴露API,客户端也是通过这些API直接访问服务,但这会导致一些安全性、运维和扩展性的问题。之后,企业也开始意识到需要一种中间层来管理和控制这种客户端到服务的通信行为,并确保服务的可靠性和安全性,于是开始有了API网关的概念。

  • API网关的兴起

早期的API网关,其主要功能就是单纯的路由和转发。API网关将请求从客户端转发到后端服务,并将后端服务的响应返回给客户端。在这个阶段,API网关的功能非常简单,主要用于解决客户端和后端服务之间的通信问题。

  • API网关的成熟

随着微服务架构的兴起和API应用的不断发展,企业开始将应用程序进一步拆分成更小的、独立部署的微服务。每个对外暴露的微服务都有自己的API,并通过API网关进行统一管理和访问。API网关在微服务架构中的作用变得更加重要,它的功能也逐渐丰富起来了。

在这一阶段,它不仅负责路由和转发请求,API网关还增加了安全和治理的功能,可以满足几个不同领域的微服务需求。比如:API网关可以通过身份认证、授权、访问控制等功能来保护API的安全;通过基于重试、超时、熔断的容错机制等来对API的访问进行治理;通过日志记录、基于指标收集以及Tracing等对API的访问进行观测与监控;支持实时的服务发现等。


API网关(图来自网络)

  • API网关的云原生化

随着云原生技术的发展,如容器化和服务网格(Service Mesh)等,API网关也在不断演进和适应新的环境。在云原生环境中,API网关实现了与容器编排系统(如Kubernetes)和服务网格集成,其自身也可以作为一个云原生服务来部署,以实现更高的可伸缩性、弹性和自动化。同时,新的技术和标准也不断涌现,如GraphQL和gRPC等,API网关也增加了对这些新技术的集成和支持。

1.2 API网关的主要功能特性

从上面的演化历史我们看到:API网关的演进使其从最初简单的请求转发角色,逐渐成为整个API管理和微服务架构中的关键组件。它不仅扮演着API管理层与后端服务层之间的适配器,也是云原生架构中不可或缺的基础设施,使微服务管理更加智能化和自动化。下面是现代API网关承担的主要功能特性,我们后续也会基于这些特性进行示例说明:

  • 请求转发和路由
  • 身份认证和授权
  • 流量控制和限速
  • 高可用与容错处理
  • 监控和可观测性

2. 那些主流的API网关

下面是来自CNCF Landscape中的主流API网关集合(截至2023.11月),图中展示了关于各个网关的一些细节,包括star数量和背后开发的公司或组织:

主流的API网关还有各大公有云提供商的实现,比如:Amazon的API GatewayGoogle Cloud的API Gateway以及上图中的Azure API Management等,但它们不在我们选择范围之内;虽然被CNCF收录,但多数API网关受到的关注并不高,超过1k star的不到30%,这些不是很受关注或dev不是那么active的项目也无法在生产环境担当关键角色;而像APISIXKong这两个受关注很高的网关,它们是建构在Nginx之上实现的,技术栈与我们不契合;而像EMISSARY INGRESS、Gloo等则是完全云原生化或者说是Kubernetes Native的,无法在无Kubernetes的基于VM或裸金属的环境下部署和运行。

好吧,剩下的只有几个Go实现的API Gateway了,在它们之中,我们选择用Tyk API网关来作为后续API功能演示的示例。

注:这并不代表Tyk API网关就要比其他Go实现的API Gateway优秀,只是它的资料比较齐全,适合在本文中作演示罢了。

3. API网关主要功能特性示例(Tyk API网关版本)

3.1 Tyk API网关简介

记得在至少5年前就知道Tyk API网关的存在,印象中它是使用Go语言开发的早期的那批API网关之一。Tyk从最初的纯开源项目,到如今由背后商业公司支持,以Open Core模式开源的网关,一直保持了active dev的状态。经过多年的演进,它已经一款功能强大的开源兼商业API管理和网关解决方案,提供了全面的功能和工具,帮助开发者有效地管理、保护和监控API。同时,Tyk API网关支持多种安装部署方式,即可以单一程序的方式放在物理机或VM上运行,也可以支持容器部署,通过docker-compose拉起,亦可以通过Kubernetes Operator将其部署在Kubernetes中,这也让Tyk API网关具备了在各大公有云上平滑迁移的能力。

关于Tyk API网关开源版本的功能详情,可以点击左边超链接到其官网查阅,这里不赘述。

3.2 安装Tyk API网关

下面我们就来安装一下Tyk API网关,我们直接在VM上安装,VM上的环境是CentOS 7.9。Tyk API提供了很多中安装方法,这里使用CentOS的yum包管理工具安装Tyk API网关,大体步骤如下(演示均以root权限操作)。

3.2.1 创建tyk gateway软件源

默认的yum repo中是不包含tyk gateway的,我们需要在/etc/yum.repos.d下面创建一个新的源,即新建一个tyk_tyk-gateway.repo文件,其内容如下:

[tyk_tyk-gateway]
name=tyk_tyk-gateway
baseurl=https://packagecloud.io/tyk/tyk-gateway/el/7/$basearch
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/tyk/tyk-gateway/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

[tyk_tyk-gateway-source]
name=tyk_tyk-gateway-source
baseurl=https://packagecloud.io/tyk/tyk-gateway/el/7/SRPMS
repo_gpgcheck=1
gpgcheck=0
enabled=1
gpgkey=https://packagecloud.io/tyk/tyk-gateway/gpgkey
sslverify=1
sslcacert=/etc/pki/tls/certs/ca-bundle.crt
metadata_expire=300

接下来我们执行下面命令来创建tyk_tyk-gateway这个repo的YUM缓存:

$yum -q makecache -y --disablerepo='*' --enablerepo='tyk_tyk-gateway'
导入 GPG key 0x5FB83118:
 用户ID     : "https://packagecloud.io/tyk/tyk-gateway (https://packagecloud.io/docs#gpg_signing) <support@packagecloud.io>"
 指纹       : 9179 6215 a875 8c40 ab57 5f03 87be 71bd 5fb8 3118
 来自       : https://packagecloud.io/tyk/tyk-gateway/gpgkey

repo配置和缓存完毕后,我们就可以安装Tyk API Gateway了:

$yum install -y tyk-gateway

安装后的tky-gateway将以一个systemd daemon服务的形式存在于主机上,程序意外退出或虚机重启后,该服务也会被systemd自动拉起。通过systemctl status命令可以查看服务的运行状态:

# systemctl status tyk-gateway
● tyk-gateway.service - Tyk API Gateway
   Loaded: loaded (/usr/lib/systemd/system/tyk-gateway.service; enabled; vendor preset: disabled)
   Active: active (running) since 日 2023-11-19 20:22:44 CST; 12min ago
 Main PID: 29306 (tyk)
    Tasks: 13
   Memory: 19.6M
   CGroup: /system.slice/tyk-gateway.service
           └─29306 /opt/tyk-gateway/tyk --conf /opt/tyk-gateway/tyk.conf

11月 19 20:34:54 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:34:54" level=error msg="Connection to Redis faile...b-sub
11月 19 20:35:04 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:35:04" level=error msg="cannot set key in pollerC...ured"
11月 19 20:35:04 iZ2ze18rmx2avqb5xgb4omZ tyk[29306]: time="Nov 19 20:35:04" level=error msg="Redis health check failed...=main
Hint: Some lines were ellipsized, use -l to show in full.

3.2.2 安装redis

我们看到tyk-gateway已经成功启动,但从其服务日志来看,它在连接redis时报错了!tyk gateway默认将数据存储在redis中,为了让tyk gateway正常运行,我们还需要安装redis!这里我们使用容器的方式安装和运行一个redis服务:

$docker pull redis:6.2.14-alpine3.18
$docker run -d --name my-redis -p 6379:6379 redis:6.2.14-alpine3.18
e5d1ec8d5f5c09023d1a4dd7d31d293b2d7147f1d9a01cff8eff077c93a9dab7

拉取并运行redis后,我们通过redis-cli验证一下与redis server的连接:

# docker run -it --rm redis:6.2.14-alpine3.18  redis-cli -h 192.168.0.24
192.168.0.24:6379>

我们看到可以正常连接!但此时Tyk Gateway仍然无法与redis正常连接,我们还需要对Tyk Gateway做一些配置调整!

3.2.3 配置Tyk Gateway

yum默认将Tyk Gateway安装到/opt/tyk-gateway下面,这个路径下的文件布局如下:

$tree -F -L 2 .
.
├── apps/
│   └── app_sample.json
├── coprocess/
│   ├── api.h
│   ├── bindings/
│   ├── coprocess_common.pb.go
│   ├── coprocess_mini_request_object.pb.go
│   ├── coprocess_object_grpc.pb.go
│   ├── coprocess_object.pb.go
│   ├── coprocess_response_object.pb.go
│   ├── coprocess_return_overrides.pb.go
│   ├── coprocess_session_state.pb.go
│   ├── coprocess_test.go
│   ├── dispatcher.go
│   ├── grpc/
│   ├── lua/
│   ├── proto/
│   ├── python/
│   └── README.md
├── event_handlers/
│   └── sample/
├── install/
│   ├── before_install.sh*
│   ├── data/
│   ├── init_local.sh
│   ├── inits/
│   ├── post_install.sh*
│   ├── post_remove.sh*
│   ├── post_trans.sh
│   └── setup.sh*
├── middleware/
│   ├── ottoAuthExample.js
│   ├── sampleMiddleware.js
│   ├── samplePostProcessMiddleware.js
│   ├── samplePreProcessMiddleware.js
│   ├── testPostVirtual.js
│   ├── testVirtual.js
│   └── waf.js
├── policies/
│   └── policies.json
├── templates/
│   ├── breaker_webhook.json
│   ├── default_webhook.json
│   ├── error.json
│   ├── monitor_template.json
│   └── playground/
├── tyk*
└── tyk.conf

其中tyk.conf就是tyk gateway的配置文件,我们先看看其默认的内容:

$cat /opt/tyk-gateway/tyk.conf
{
  "listen_address": "",
  "listen_port": 8080,
  "secret": "xxxxxx",
  "template_path": "/opt/tyk-gateway/templates",
  "use_db_app_configs": false,
  "app_path": "/opt/tyk-gateway/apps",
  "middleware_path": "/opt/tyk-gateway/middleware",
  "storage": {
    "type": "redis",
    "host": "redis",
    "port": 6379,
    "username": "",
    "password": "",
    "database": 0,
    "optimisation_max_idle": 2000,
    "optimisation_max_active": 4000
  },
  "enable_analytics": false,
  "analytics_config": {
    "type": "",
    "ignored_ips": []
  },
  "dns_cache": {
    "enabled": false,
    "ttl": 3600,
    "check_interval": 60
  },
  "allow_master_keys": false,
  "policies": {
    "policy_source": "file"
  },
  "hash_keys": true,
  "hash_key_function": "murmur64",
  "suppress_redis_signal_reload": false,
  "force_global_session_lifetime": false,
  "max_idle_connections_per_host": 500
}

我们看到:storage下面存储了redis的配置信息,我们需要将redis的host配置修改为我们的VM地址:

    "host": "192.168.0.24",

然后重启Tyk Gateway服务:

$systemctl daemon-reload
$systemctl restart tyk-gateway

之后,我们再查看tyk gateway的运行状态:

systemctl status tyk-gateway
● tyk-gateway.service - Tyk API Gateway
   Loaded: loaded (/usr/lib/systemd/system/tyk-gateway.service; enabled; vendor preset: disabled)
   Active: active (running) since 一 2023-11-20 06:54:07 CST; 41s ago
 Main PID: 20827 (tyk)
    Tasks: 15
   Memory: 24.8M
   CGroup: /system.slice/tyk-gateway.service
           └─20827 /opt/tyk-gateway/tyk --conf /opt/tyk-gateway/tyk.conf

11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Loading API configurations...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Tracking hostname" api_nam...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Initialising Tyk REST API ...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API bind on custom port:0"...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Checking security policy: ...fault
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API Loaded" api_id=1 api_n...ip=--
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Loading uptime tests..." p...k-mgr
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="Initialised API Definition...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=warning msg="All APIs are protected ...=main
11月 20 06:54:07 iZ2ze18rmx2avqb5xgb4omZ tyk[20827]: time="Nov 20 06:54:07" level=info msg="API reload complete" prefix=main
Hint: Some lines were ellipsized, use -l to show in full.

从服务日志来看,现在Tyk Gateway可以正常连接redis并提供服务了!我们也可以通过下面的命令验证网关的运行状态:

$curl localhost:8080/hello
{"status":"pass","version":"5.2.1","description":"Tyk GW","details":{"redis":{"status":"pass","componentType":"datastore","time":"2023-11-20T06:58:57+08:00"}}}

“/hello”是Tyk Gateway的内置路由,由Tyk网关自己提供服务。

到这里Tyk Gateway的安装和简单配置就结束了,接下来,我们就来看看API Gateway的主要功能特性,并借助Tyk Gateway来展示一下这些功能特性。

注:查看Tyk Gateway的运行日志,可以使用journalctl -u tyk-gateway -f命令实时follow最新日志输出。

3.3 功能特性:请求转发与路由

请求转发和路由是API Gateway的主要功能特性之一,API Gateway可以根据请求的路径、方法、查询参数等信息将请求转发到相应的后端服务,其内核与反向代理类似,不同之处在于API Gateway增加了“API”这层抽象,更加专注于构建、管理和增强API。

下面我们来看看Tyk如何配置API路由,我们首先创建一个新API。

3.3.1 创建一个新API

Tyk开源版支持两种创建API的方式,一种是通过调用Tyk的控制类API,一种则是通过传统的配置文件,放入特定目录下。无论哪种方式添加完API,最终都要通过Tyk Gateway热加载(hot reload)或重启才能生效。

注:Tyk Gateway的商业版本提供Dashboard,可以以图形化的方式管理API,并且商业版本的API定义会放在Postgres或MongoDB中,我们这里用开源版本,只能手工管理了,并且API定义只能放在文件中。

下面,我们就来在Tyk上创建一个新的API路由,该路由示例的示意图如下:

在未添加新API之前,我们使用curl访问一下该API路径:

$curl localhost:8080/api/v1/no-authn
Not Found

Tyk Gateway由于找不到API路由,返回Not Found。接下来,我们采用调用tyk gateway API的方式来添加路由:

$curl -v -H "x-tyk-authorization: {tyk gateway secret}" \
  -s \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{
    "name": "no-authn-v1",
    "slug": "no-authn-v1",
    "api_id": "no-authn-v1",
    "org_id": "1",
    "use_keyless": true,
    "auth": {
      "auth_header_name": "Authorization"
    },
    "definition": {
      "location": "header",
      "key": "x-api-version"
    },
    "version_data": {
      "not_versioned": true,
      "versions": {
        "Default": {
          "name": "Default",
          "use_extended_paths": true
        }
      }
    },
    "proxy": {
      "listen_path": "/api/v1/no-authn",
      "target_url": "http://localhost:18081/",
      "strip_listen_path": true
    },
    "active": true
}' http://localhost:8080/tyk/apis | python -mjson.tool 

* About to connect() to localhost port 8080 (#0)
*   Trying ::1...
* Connected to localhost (::1) port 8080 (#0)
> POST /tyk/apis HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8080
> Accept: */*
> x-tyk-authorization: {tyk gateway secret}
> Content-Type: application/json
> Content-Length: 797
>
} [data not shown]
* upload completely sent off: 797 out of 797 bytes
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Wed, 22 Nov 2023 05:38:40 GMT
< Content-Length: 53
<
{ [data not shown]
* Connection #0 to host localhost left intact
{
    "action": "added",
    "key": "no-authn-v1",
    "status": "ok"
}

从curl返回结果我们看到:API已经被成功添加。这时tyk gateway的安装目录/opt/tyk-gateway的子目录apps下会新增一个名为no-authn-v1.json的配置文件,这个文件内容较多,有300行,这里就不贴出来了,这个文件就是新增的no-authn API的定义文件

不过此刻,Tyk Gateway还需热加载后才能为新的API提供服务,调用下面API可以触发Tyk Gateway的热加载:

$curl -H "x-tyk-authorization: {tyk gateway secret}" -s http://localhost:8080/tyk/reload/group | python -mjson.tool
{
    "message": "",
    "status": "ok"
}

注:即便触发热加载成功,但如果body中的json格式错,比如多了一个结尾逗号,Tyk Gateway是不会报错的!

API路由创建完毕并生效后,我们再来访问一下API:

$ curl localhost:8080/api/v1/no-authn
{
    "error": "There was a problem proxying the request"
}

我们看到:Tyk Gateway返回的已经不是“Not Found”了!现在我们创建一下no-authn这个API服务,考虑到适配更多后续示例,这里建立这样一个http server:

// api-gateway-examples/httpserver

func main() {
    // 解析命令行参数
    port := flag.Int("p", 8080, "Port number")
    apiVersion := flag.String("v", "v1", "API version")
    apiName := flag.String("n", "example", "API name")
    flag.Parse()                                         

    // 注册处理程序
    http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        fmt.Println(*r)
        fmt.Fprintf(w, "Welcome api: localhost:%d/%s/%s\n", *port, *apiVersion, *apiName)
    })                                                                                     

    // 启动HTTP服务器
    addr := fmt.Sprintf(":%d", *port)
    log.Printf("Server listening on port %d\n", *port)
    log.Fatal(http.ListenAndServe(addr, nil))
}

我们启动一个该http server的实例:

$go run main.go -p 18081 -v v1 -n no-authn
2023/11/22 22:02:42 Server listening on port 18081

现在我们再通过tyk gateway调用一下no-authn这个API:

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

我们看到这次路由通了!no-authn API返回了期望的结果!

3.3.2 负载均衡

如果no-authn API存在多个服务实例,Tyk Gateway也可以将请求流量负载均衡到多个no-authn服务实例上去,下图是Tyk Gateway进行请求流量负载均衡的示意图:

要实现负责均衡,我们需要调整no-authn API的定义,这次我们直接修改/opt/tyk-gateway/apps/no-authn-v1.json,变更的配置主要有三项:

// /opt/tyk-gateway/apps/no-authn-v1.json

  "proxy": {
    "preserve_host_header": false,
    "listen_path": "/api/v1/no-authn",
    "target_url": "",                  // (1) 改为""
    "disable_strip_slash": false,
    "strip_listen_path": true,
    "enable_load_balancing": true,     // (2) 改为true
    "target_list": [                   // (3) 填写no-authn服务实例列表
      "http://localhost:18081/",
      "http://localhost:18082/",
      "http://localhost:18083/"
    ],

修改完配置后,调用Tyk的控制类API使之生效,然后我们启动三个no-authn的API实例:

$go run main.go -p 18081 -v v1 -n no-authn
$go run main.go -p 18082 -v v1 -n no-authn
$go run main.go -p 18083 -v v1 -n no-authn

接下来,我们多次调用curl访问no-authn API:

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18083/v1/no-authn

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18083/v1/no-authn

我们看到:Tyk Gateway在no-authn API的各个实例之间做了等权重的轮询。如果我们停掉实例3,再来访问该API,我们将得到下面结果:

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Bad Request

$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Welcome api: localhost:18082/v1/no-authn
$curl localhost:8080/api/v1/no-authn
Bad Request

注:Tyk Gateway商业版通过Dashboard支持配置带权重的RR负载均衡算法

我们看到:实例3已经下线,但Tyk Gateway并不会跳过该已经下线的实例,这在生产环境会给客户端带来不一致的响应。

3.3.3 服务实例存活检测(uptime test)

Tyk Gateway在开启负载均衡的时候,也提供了对后端服务实例的存活检测机制,当某个服务实例down了后,负载均衡机制会绕过该实例将请求发到下一个处于存活状态的实例;而当down机实例恢复后,Tyk Gateway也能及时检测到服务实例上线,并将其加入流量负载调度。

支持存活检测(uptime test)的API定义配置如下:

// /opt/tyk-gateway/apps/no-authn-v1.json

"uptime_tests": {
    "disable": false,
    "poller_group":"",
    "check_list": [
      {
        "url": "http://localhost:18081/"
      },
      {
        "url": "http://localhost:18082/"
      },
      {
        "url": "http://localhost:18083/"
      }
    ],
    "config": {
      "enable_uptime_analytics": true,
      "failure_trigger_sample_size": 3,
      "time_wait": 300,
      "checker_pool_size": 50,
      "expire_utime_after": 0,
      "service_discovery": {
        "use_discovery_service": false,
        "query_endpoint": "",
        "use_nested_query": false,
        "parent_data_path": "",
        "data_path": "",
        "port_data_path": "",
        "target_path": "",
        "use_target_list": false,
        "cache_disabled": false,
        "cache_timeout": 0,
        "endpoint_returns_list": false
      },
      "recheck_wait": 0
    }
}

"proxy": {
    ... ...
    "enable_load_balancing": true,
    "target_list": [
      "http://localhost:18081/",
      "http://localhost:18082/",
      "http://localhost:18083/"
    ],
    "check_host_against_uptime_tests": true,
    ... ...
}

我们新增了uptime_tests的配置,uptime_tests的check_list中的url的值要与proxy中target_list中的值完全一样,这样Tyk Gateway才能将二者对应上。另外proxy的check_host_against_uptime_tests要设置为true。

这样配置并生效后,等我们将服务实例3停掉后,后续到no-authn的请求就只会转发到实例1和实例2了。而当恢复实例3运行后,Tyk Gateway又会将流量分担到实例3上。

3.3.4 动态负载均衡

上面负载均衡示例中target_list中的目标实例的IP和端口的手工配置的,而在云原生时代,我们经常会基于容器承载API服务实例,当容器因故退出,并重新启动一个新容器时,IP可能会发生变化,这样上述的手工配置就无法满足要求,这就对API Gateway提出了与服务发现组件集成的要求:通过服务发现组件动态获取服务实例的访问列表,进而实现动态负载均衡

Tyk Gateway内置了主流服务发现组件(比如Etcd、Consul、ZooKeeper等)的对接能力,鉴于环境所限,这里就不举例了,大家可以在Tyk Gateway的服务发现示例文档页面找到与不同服务发现组件对接时的配置示例。

3.3.5 IP访问限制

针对每个API,API网关还提供IP访问限制的特性,比如Tyk Gateway就提供了IP白名单IP黑名单功能,通常二选一开启一种限制即可。

以白名单为例,即凡是在白名单中的IP才被允许访问该API。下面是白名单配置样例:

// /opt/tyk-gateway/apps/no-authn-v1.json

  "enable_ip_whitelisting": true,
  "allowed_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14"],

生效后,当我们访问no-authn API时,会得到下面错误:

$curl localhost:8080/api/v1/no-authn
{
    "error": "access from this IP has been disallowed"
}

如果开启的是黑名单,那么凡是在黑名单中的IP都被禁止访问该API,下面是黑名单配置样例:

// /opt/tyk-gateway/apps/no-authn-v1.json

  "enable_ip_blacklisting": true,
  "blacklisted_ips": ["12.12.12.12", "12.12.12.13", "12.12.12.14", "127.0.0.1"],

生效后,当我们访问no-authn API时,会得到如下结果:

$curl 127.0.0.1:8080/api/v1/no-authn
{
    "error": "access from this IP has been disallowed"
}

到目前为止,我们的API网关和定义的API都处于“裸奔”状态,因为没有对客户端进行身份认证,任何客户端都可以访问到我们的API,显然这不是我们期望的,接下来,我们就来看看API网关的一个重要功能特性:身份认证与授权。

3.4 功能特性:身份认证和授权

在《通过实例理解Go Web身份认证的几种方式》一文中,我们提到过:建立全局的安全通道是任何身份认证方式的前提

3.4.1 建立安全通道,卸载TLS证书

Tyk Gateway支持在Gateway层面统一配置TLS证书,同时也起到在Gateway卸载TLS证书的作用:

这次我们要在tyk.conf中进行配置,才能在Gateway层面生效。这里我们借用《通过实例理解Go Web身份认证的几种方式》一文中生成的几个证书(大家可以在https://github.com/bigwhite/experiments/tree/master/authn-examples/tls-authn/make_certs下载),并将它们放到/opt/tyk-gateway/certs/下面:

$ls /opt/tyk-gateway/certs/
server-cert.pem  server-key.pem

然后,我们在/opt/tyk-gateway/tyk.conf文件中增加下面配置:

// /opt/tyk-gateway/tyk.conf 

  "http_server_options": {
    "use_ssl": true,
    "certificates": [
      {
        "domain_name": "server.com",
        "cert_file": "./certs/server-cert.pem",
        "key_file": "./certs/server-key.pem"
      }
    ]
  }

之后,重启tyk gateway服务,使得tyk.conf的配置修改生效。

注:在/etc/hosts中设置server.com为127.0.0.1。

现在我们用之前的http方式访问一下no-authn的API:

$curl server.com:8080/api/v1/no-authn
Client sent an HTTP request to an HTTPS server.

由于全局启用了HTTPS,采用http方式的请求将被拒绝。我们换成https方式访问:

// 不验证服务端证书
$curl -k https://server.com:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

// 验证服务端的自签证书
$curl --cacert ./inter-cert.pem https://server.com:8080/api/v1/no-authn
Welcome api: localhost:18081/v1/no-authn

3.4.2 Mutual TLS双向认证

在《通过实例理解Go Web身份认证的几种方式》一文中,我们介绍的第一种身份认证方式就是TLS双向认证,那么Tyk Gateway对MTLS的支持如何呢?Tyk官方文档提到它既支持client mTLS,也支持upstream mTLS

我们更关心的是client mTLS,即客户端在与Gateway建连后,Gateway会使用Client CA验证客户端的证书!我最初认为这个Client CA的配置是在tyk.conf中,但找了许久,也没有发现配置Client CA的地方。

在no-authn API的定义文件(no-authn-v1.json)中,我们做如下配置改动:

  "use_mutual_tls_auth": true,
  "client_certificates": [
      "/opt/tyk-gateway/certs/inter-cert.pem"
  ],

但使用下面命令访问API时报错:

$curl --key ./client-key.pem --cert ./client-cert.pem --cacert ./inter-cert.pem https://server.com:8080/api/v1/no-authn
{
    "error": "Certificate with SHA256 bc8717c0f2ea5a0b81813abb3ec42ef8f9bf60da251b87243627d65fb0e3887b not allowed"
}

如果将”client_certificates”的配置中的inter-cert.pem改为client-cert.pem,则是可以的,但个人感觉这很奇怪,不符合逻辑,将tyk gateway的文档、issue甚至代码翻了又翻,也没找到合理的配置client CA的位置。

Tyk Gateway支持多种身份认证方式,下面我们来看一种使用较为广泛的方式:JWT Auth。

主要JWT身份认证方式的原理和详情,可以参考我之前的文章《通过实例理解Go Web身份认证的几种方式》。

3.4.3 JWT Token Auth

下面是我为这个示例做的一个示意图:

这是我们日常开发中经常遇到的场景,即通过portal用用户名和密码登录后便可以拿到一个jwt token,然后后续的访问功能API的请求仅携带该jwt token即可。API Gateway对于portal/login API不做任何身份认证;而对后续的功能API请求,通过共享的secret(也称为static secret)对请求中携带的jwt token进行签名验证。

portal/login API由于不进行authn,这样其配置与前面的no-authn API几乎一致,只是API名称、路径和target_list有不同:

// apps/portal-login-v1.json

{
  "name": "portal-login-v1",
  "slug": "portal-login-v1",
  "listen_port": 0,
  "protocol": "",
  "enable_proxy_protocol": false,
  "api_id": "portal-login-v1",
  "org_id": "1",
  "use_keyless": true,
  ... ...
  "proxy": {
    "preserve_host_header": false,
    "listen_path": "/api/v1/portal/login",
    "target_url": "",
    "disable_strip_slash": false,
    "strip_listen_path": true,
    "enable_load_balancing": true,
    "target_list": [
      "http://localhost:28084"
    ],
    "check_host_against_uptime_tests": true,
  ... ...
}

对应的portal login API也不复杂:

// api-gateway-examples/portal-login/main.go

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/golang-jwt/jwt/v5"
)

func main() {
    // 创建一个基本的HTTP服务器
    mux := http.NewServeMux()

    username := "admin"
    password := "123456"
    key := "iamtonybai"

    // for uptime test
    mux.HandleFunc("/health", func(w http.ResponseWriter, req *http.Request) {
        w.WriteHeader(http.StatusOK)
    })

    // login handler
    mux.HandleFunc("/", func(w http.ResponseWriter, req *http.Request) {
        // 从请求头中获取Basic Auth认证信息
        user, pass, ok := req.BasicAuth()
        if !ok {
            // 认证失败
            w.WriteHeader(http.StatusUnauthorized)
            return
        }

        // 验证用户名密码
        if user == username && pass == password {
            // 认证成功,生成token
            token := jwt.NewWithClaims(jwt.SigningMethodHS256, jwt.MapClaims{
                "username": username,
                "iat":      jwt.NewNumericDate(time.Now()),
            })
            signedToken, _ := token.SignedString([]byte(key))
            w.Write([]byte(signedToken))
        } else {
            // 认证失败
            http.Error(w, "Invalid username or password", http.StatusUnauthorized)
        }
    })

    // 监听28084端口
    err := http.ListenAndServe(":28084", mux)
    if err != nil {
        log.Fatal(err)
    }
}

运行该login API服务后,我们用curl命令获取一下jwt token:

$curl -u 'admin:123456' -k https://server.com:8080/api/v1/portal/login
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA

现在我们再来建立protected API:

// apps/protected-v1.json

{
  "name": "protected-v1",
  "slug": "protected-v1",
  "listen_port": 0,
  "protocol": "",
  "enable_proxy_protocol": false,
  "api_id": "protected-v1",
  "org_id": "1",
  "use_keyless": false,    // 设置为false, gateway才会进行jwt的验证
  ... ...
  "enable_jwt": true,      // 开启jwt
  "use_standard_auth": false,
  "use_go_plugin_auth": false,
  "enable_coprocess_auth": false,
  "custom_plugin_auth_enabled": false,
  "jwt_signing_method": "hmac",        // 设置alg为hs256
  "jwt_source": "aWFtdG9ueWJhaQ==",    // 设置共享secret: base64("iamtonybai")
  "jwt_identity_base_field": "username", // 设置代表请求中的用户身份的字段,这里我们用username
  "jwt_client_base_field": "",
  "jwt_policy_field_name": "",
  "jwt_default_policies": [
     "5e189590801287e42a6cf5ce"        // 设置security policy,这个似乎是jwt auth必须的
  ],
  "jwt_issued_at_validation_skew": 0,
  "jwt_expires_at_validation_skew": 0,
  "jwt_not_before_validation_skew": 0,
  "jwt_skip_kid": false,
  ... ...
  "version_data": {
    "not_versioned": true,
    "default_version": "",
    "versions": {
      "Default": {
        "name": "Default",
        "expires": "",
        "paths": {
          "ignored": null,
          "white_list": null,
          "black_list": null
        },
        "use_extended_paths": true,
        "extended_paths": {
          "persist_graphql": null
        },
        "global_headers": {
          "username": "$tyk_context.jwt_claims_username" // 设置转发到upstream的请求中的header字段username
        },
        "global_headers_remove": null,
        "global_response_headers": null,
        "global_response_headers_remove": null,
        "ignore_endpoint_case": false,
        "global_size_limit": 0,
        "override_target": ""
      }
    }
  },
  ... ...
  "enable_context_vars": true, // 开启上下文变量
  "config_data": null,
  "config_data_disabled": false,
  "tag_headers": ["username"], // 设置header
  ... ...
}

这个配置就相对复杂许多,也是翻阅了很长时间资料才验证通过的配置。JWT Auth必须有关联的policy设置,我们在tyk gateway开源版中要想设置policy,需要现在tyk.conf中做如下设置:

// /opt/tyk-gateway/tyk.conf

  "policies": {
    "policy_source": "file",
    "policy_record_name": "./policies/policies.json"
  },

而policies/policies.json的内容如下:

// /opt/tyk-gateway/policies/policies.json
{
    "5e189590801287e42a6cf5ce": {
        "rate": 1000,
        "per": 1,
        "quota_max": 100,
        "quota_renewal_rate": 60,
        "access_rights": {
            "protected-v1": {
                "api_name": "protected-v1",
                "api_id": "protected-v1",
                "versions": [
                    "Default"
                ]
            }
        },
        "org_id": "1",
        "hmac_enabled": false
    }
}

上述设置完毕并重启tyk gateway生效后,且protected api服务也已经启动时,我们访问一下该API服务:

$curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA" -k https://server.com:8080/api/v1/protected
invoke protected api ok

我们看到curl发出的请求成功通过了Gateway的验证!并且通过protected API输出的请求信息来看,Gateway成功解析出username,并将其作为Header中的字段传递给了protected API服务实例:

http.Request{Method:"GET", URL:(*url.URL)(0xc0002f6240), Proto:"HTTP/1.1", ProtoMajor:1, ProtoMinor:1, Header:http.Header{"Accept":[]string{"*/*"}, "Accept-Encoding":[]string{"gzip"}, "Authorization":[]string{"Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE3MDA3NTEyODEsInVzZXJuYW1lIjoiYWRtaW4ifQ.-wC8uPsLHDxSXcEMxIxJ8O2l3aWtWtWKvhtmuHmgIMA"}, "User-Agent":[]string{"curl/7.29.0"}, "Username":[]string{"admin"}, "X-Forwarded-For":[]string{"127.0.0.1"}}, Body:http.noBody{}, GetBody:(func() (io.ReadCloser, error))(nil), ContentLength:0, TransferEncoding:[]string(nil), Close:false, Host:"localhost:28085", Form:url.Values(nil), PostForm:url.Values(nil), MultipartForm:(*multipart.Form)(nil), Trailer:http.Header(nil), RemoteAddr:"[::1]:55583", RequestURI:"/", TLS:(*tls.ConnectionState)(nil), Cancel:(<-chan struct {})(nil), Response:(*http.Response)(nil), ctx:(*context.cancelCtx)(0xc0002e34f0)}

如果不携带Authorization头字段或jwt的token是错误的,那么结果将如下所示:

$ curl -k https://server.com:8080/api/v1/protected
{
    "error": "Authorization field missing"
}

$ curl -k -H "Authorization: Bearer xxx" https://server.com:8080/api/v1/protected
{
    "error": "Key not authorized"
}

一旦通过API Gateway的身份认证,上游的API服务就会拿到客户端身份,有了唯一身份后,就可以进行授权操作了,其实policy设置本身也是一种授权访问控制。Tyk Gateway自身也支持RBAC等模型,也支持与OPA(open policy agent)等的集成,但更多是在商业版的tyk dashboard下完成的,这里也就不重点说明了。

下面的Gateway的几个主要功能特性由于试验环境受限以及文章篇幅考量,我不会像上述例子这么细致的说明了,只会简单说明一下。

3.5 功能特性:流量控制与限速

Tyk Gateway内置提供了强大的流量控制功能,可以通过全局级别和API级别的限速来管理请求流量。此外,Tyk Gateway 还支持请求配额(request quota)来限制每个用户或应用程序在一个时间周期内的请求次数。

流量不仅和请求速度和数量有关系,与请求的大小也有关系,Tyk Gateway还支持在全局层面和API层面设置Request的size limit,以避免超大包对网关运行造成不良影响。

3.6 功能特性:高可用与容错处理

在许多情况下,我们要为客户确保服务水平(service level),比如:最大往返时间、最大响应时延等。Tyk Gateway提供了一系列功能,可帮助我们确保网关的高可用运行和SLA服务水平。

Tyk支持健康检查,这对于确定Tyk Gateway的状态极为重要,没有健康检查,就很难知道网关的实际运行状态如何。

Tyk Gateway还内置了断路器(circuit breaker),这个断路器是基于比例的,因此如果y个请求中的x请求都失败了,断路器就会跳闸,例如,如果x = 10,y = 100,则阈值百分比为10%。当失败比例到达10%时,断路器就会切断流量,同时跳闸还会触发一个事件,我们可以记录和处理该事件。

当upstream的服务响应迟迟不归时,Tyk Gateway还可以设置强制超时,可以确保服务始终在给定时间内响应。这在高可用性系统中非常重要,因为在这种系统中,响应性能至关重要,这样才能干净利落地处理错误。

3.7 功能特性:监控与可观测性

微服务时代,可观测性对运维以及系统高可用的重要性不言而喻。Tyk Gateway在多年的演化过程中,也逐渐增加了对可观测的支持,

可观测主要分三大块:

  • log

Tyk Gateway支持设置输出日志的级别(log level),默认是info级别。Tyk输出的是结构化日志,这使得它可以很好的与其他日志收集查询系统集成,Tyk支持与主流的日志收集工具对接,包括:logstash、sentry、Graylog、Syslog等。

  • metrics

度量数据是反映网关系统健康状况、错误计数和类型、IT基础设施(服务器、虚拟机、容器、数据库和其他后端组件)及其他流程的硬件资源数据的重要参考。运维团队可以通过使用监控工具来利用实时度量的数据,识别运行趋势、在系统故障时设置警报、确定问题的根本原因并缓解问题。

Tyk Gateway内置了对主流metrics采集方案Prometheus+Grafana的支持,可以在网关层面以及对API进行实时度量数据采集和展示。

  • tracing

Tyk Gateway从5.2版本开始支持了与服务Tracing界的标准:OpenTelemetry的集成,这样你可以使用多种支持OpenTelemetry的Tracing后端,比如Jaeger、Datadog等。Tracing可在Gateway层面开启,也可以延展到API层面。

4. 小结

本文对已经相对成熟的API网关技术做了回顾,对API网关的演进阶段、主流特性以及当前市面上的主流API网关进行了简要说明,并以Go实现的Tyk Gateway社区开源版为例,以示例方式对API网关的主要功能做了介绍。

总体而言,Tyk Gateway是一款功能强大,社区相对活跃并有商业公司支持的产品,文档很丰富,但从实际使用层面,这些文档对Tyk社区版本的使用者来说并不友好,指导性不足(更多用商业版的Dashboard说明,与配置文件难于对应),就像本文例子中那样,为了搞定JWT认证,笔者着实花了不少时间查阅资料,甚至阅读源码。

Tyk Gateway的配置设计平坦,没有层次和逻辑,感觉是随着时间随意“堆砌”上去的。并且配置文件更新时,如果出现格式问题,Tyk Gateway并不报错,让人难于确定配置是否真正生效了,只能用Tyk Gateway的控制API去查询结果来验证,非常繁琐低效。

本文涉及的源码可以在这里下载,文中涉及的一些tyk gateway api和security policy的配置也可以在其中查看。

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 Go语言编程指南
商务合作请联系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