端点#

UCS 中的端点是微服务的通信接口。UCS 将端点分为两种类型

入口 (Ingress) 端点 - 通信接口的服务器端，即微服务中监听连接的服务器。
出口 (Egress) 端点 - 通信接口的客户端，即微服务中发起与服务器连接的客户端。

UCS 端点与 server 和 client 角色相关，而非与数据流方向相关。因此，出口 (Egress) 端点连接到 入口 (Ingress) 端点。

出口 (Egress) 端点本质上只是虚拟的。但是，它们承担着重要的工作，即表示微服务依赖并连接的外部端点/API。它们还用于抽象客户端微服务中的连接详细信息（address 和 port），如创建微服务中所述。在 UCS 应用程序中，当客户端微服务的 出口 (Egress) 端点连接到 入口 (Ingress) 端点时，入口 (Ingress) 端点的连接详细信息（address 和 port）将在应用程序构建期间设置在客户端微服务上。

由于上述抽象

客户端微服务在微服务开发期间不需要预先知道 入口 (Ingress) 端点的连接详细信息。因此，微服务可以独立开发。
实现 入口 (Ingress) 端点的微服务可以很容易地被另一个实现类似兼容 入口 (Ingress) 端点的微服务替换。

端点类型	描述
HTTP	OAI/OpenAPI 规范
gRPC	https://developers.google.com/protocol-buffers/docs/proto3
RTSP	https://www.rfc-editor.org/rfc/rfc2326.html
AsyncIO	asyncapi/spec
UCX
RESP	asyncapi/spec
MongoDB Wire
原始 UDP / TCP	原始 UDP / TCP

对于 UCS 兼容的微服务，每个 入口 (Ingress) 或 出口 (Egress) 端点都附带一个端点定义文件，该文件描述了端点预期的数据交换格式。端点定义文件的格式取决于端点遵循的方案。以下部分详细描述了端点方案。

入口 (Ingress) 端点#

UCS 中的入口 (Ingress) 端点使用以下属性描述

字段	描述
名称 (name)	入口 (Ingress) 端点的字符串标识符
描述 (description)	端点的简短描述
方案 (scheme)	端点遵循的方案
数据流 (data-flow)	通过出口 (Egress) 端点的数据流。为 `in`、`out` 或 `in-out` 之一
服务 (service)	端点的服务器地址或 Kubernetes 服务抽象名称。
端口 (port)	入口 (Ingress) 端点的端口号。
协议 (protocol)	端点必须使用的网络协议。为 `TCP` 或 `UDP` 之一。

出口 (Egress) 端点#

UCS 中的出口 (Egress) 端点使用以下属性描述

字段	描述
名称 (name)	出口 (Egress) 端点的字符串标识符
描述 (description)	端点的简短描述
协议 (protocol)	端点必须使用的网络协议。为 `TCP` 或 `UDP` 之一
方案 (scheme)	端点遵循的方案
强制性 (mandatory)	布尔值，指示连接出口 (Egress) 端点对于微服务正常工作是否是强制性的
数据流 (data-flow)	通过出口 (Egress) 端点的数据流。为 `in`、`out` 或 `in-out` 之一

UCS 端点方案#

HTTP#

由字符串枚举 http 表示。它供使用 HTTP 协议进行通信的端点使用。

HTTP 端点方案的端点定义文件必须遵循 OpenAPI v3.0.3 规范 - OAI/OpenAPI-Specification。该文件可以是 YAML 或 JSON 格式，并且必须具有文件名 <endpoint-name>.yaml 或 <endpoint-name>.json。

示例端点定义文件

openapi: 3.0.0
info:
  title: MyService API spec
  description: MyService HTTP API
  version: 0.0.1
paths:
  /hello:
    get:
      responses:
        '200':
          description: Success response to the /hello API
      description: Check if the API is up

gRPC#

由字符串枚举 grpc 表示。它供使用 gRPC 协议进行通信的端点使用。

gRPC 端点方案的端点定义文件必须遵循 Protocol Buffer Language 规范 - https://developers.google.com/protocol-buffers/docs/proto3。它基本上是 gRPC 客户端/服务器实现中使用的 .proto 文件，并且必须具有文件名 <endpoint-name>.proto。

示例端点定义文件

syntax = "proto3";

service PingTest {
  rpc Ping (PingRequest) returns (PingReply) {}
}

message PingRequest {
  string test_message = 1;
}

message PingReply {
  string status = 1;
}

AsyncIO#

由字符串枚举 asyncio 表示。它供使用异步事件（例如使用 Kafka 或 MQTT 消息代理）进行通信的端点使用。

AsyncIO 端点方案的端点定义文件必须遵循 AsyncAPI v2.2.0 规范 - asyncapi/spec。该文件可以是 YAML 或 JSON 格式，并且必须具有文件名 <endpoint-name>.yaml 或 <endpoint-name>.json。

示例端点定义文件

asyncapi: 2.2.0
info:
  title: AsyncIO API schema for myservice-ping endpoint
  version: 0.0.1
channels:
  ping:
    publish:
      message:
        payload:
          type: string
          pattern: PING

RTSP#

由字符串枚举 rtsp 表示。它供使用 RTSP 进行流数据传输的端点使用。

RTSP 端点方案的端点定义文件必须遵循 JSON 模式

{
    "$schema": "http://json-schema.fullstack.org.cn/draft-07/schema",
    "$id": "ucf-rtsp-ep-1.0.0",
    "title": " UCS RTSP Endpoint",
    "description": "The object defines UCS RTSP Endpoint Specification",
    "type": "object",
    "required": [
        "mediaPath"
    ],
    "properties": {
        "mediaPath": {
            "description": "Streaming Media Path",
            "type": "string"
        },
        "user": {
            "description": "Username for accessing the RTSP server",
            "type": "string"
        },
        "password": {
            "description": " Password for accessing the RTSP server",
            "type": "string"
        }
    }
}

该文件可以是 YAML 或 JSON 格式，并且必须具有文件名 <endpoint-name>.yaml 或 <endpoint-name>.json。

示例端点定义文件

{
    "mediaPath": "/test"
}

RESP#

由字符串枚举 resp 表示。它供通过 RESP (REdis Serialization Protocol) 使用 Redis 通过异步事件进行通信的端点使用。RESP 端点方案的端点定义文件必须遵循 AsyncAPI v2.2.0 规范 - asyncapi/spec。该文件可以是 YAML 或 JSON 格式，并且必须具有文件名 <endpoint-name>.yaml 或 <endpoint-name>.json。

示例端点定义文件

asyncapi: 2.2.0
info:
  title: AsyncIO API schema for myservice-ping endpoint
  version: 0.0.1
channels:
  ping:
    publish:
      message:
        payload:
          type: string
          pattern: PING

UCX#

由字符串枚举 ucx 表示。它供通过 UCX 进行通信的端点使用。

UCX 端点的端点定义文件不是必需的

MongoDB Wire#

由字符串枚举 mongodb-wire 表示。它供使用 MongoDB Wire 协议进行通信的端点使用。

MongoDB Wire 端点的端点定义文件不是必需的。

原始 UDP / TCP#

由字符串枚举 none 表示。它供在 TCP/UDP 之上实现某些其他方案的端点使用，例如 MongoDB Wire Protocol 或使用原始 UDP 数据包/TCP 套接字。

对于此方案，微服务要符合 UCS 规范，不是强制要求指定端点定义文件。

如果指定，则此端点方案的端点定义文件必须遵循 JSON 模式

{
    "$schema": "http://json-schema.fullstack.org.cn/draft-07/schema",
    "$id": "ucf-tcp-udp-ep-1.0.0",
    "title": " UCS TCP/UDP Endpoint",
    "description": "The object defines UCS TCP/UDP Endpoint Specification",
    "type": "object",
    "required": [
        "transportProtocol"
    ],
    "properties": {
        "transportProtocol": {
            "description": "Protocol for data transport. e.g. RTP / RAW etc",
            "type": "string"
        },
        "mediaType": {
            "description": "Type of media audio/video",
            "type": "string"
        },
        "mediaFormat": {
            "description": "Media Format e.g. h264/aac/raw",
            "type": "string"
        },
        "multicast": {
            "description": "Unicast or Multicast mode",
            "type": "string"
        }
    }
}

该文件可以是 YAML 或 JSON 格式，并且必须具有文件名 <endpoint-name>.yaml 或 <endpoint-name>.json。

示例端点定义文件

{
    "transportProtocol": "RTP"
}

端点连接与验证#

如最初提到的，UCS 应用程序中的连接表示客户端微服务的 出口 (Egress) 端点与服务器微服务的 入口 (Ingress) 之间的连接。

在文本表示中，连接在应用程序的 connections 字段下以格式 <client-microservice-name-with-egress-endpoint>/<egress-endpoint-name>: <server-microservice-name-with-ingress-endpoint>/<ingress-endpoint-name> 指定。

以下是应用程序中连接的示例

connections:
    hello-client/http-api: hello-server/http-api

在可视化表示（UCS Studio）中，连接表示为连接两个端口（端点）的线条。连接（线条）是彩色编码的。不同的颜色根据其连接的端点的方案使用。

UCS 应用程序构建工具 UCS Application Builder CLI 和 UCS Studio 执行基本的端点连接验证。它们验证连接的 入口 (Ingress) 和 出口 (Egress) 端点的 scheme 和 protocol 是否相同。

具有多个连接的出口 (Egress) 端点#

某些 出口 (Egress) 端点可能允许连接到多个 入口 (Ingress) 端点。如果出口 (Egress) 端点的 multi 字段设置为 true，则表示这种情况。

在文本表示中，可以在以下格式中指定多个连接 -

<microservice-name-with-egress-endpoint>/<egress-endpoint-name>: [
    <microservice-name-with-ingress-endpoint1>/<ingress-endpoint-name1>,
    <microservice-name-with-ingress-endpoint2>/<ingress-endpoint-name2>
]

以下是一个示例

connections:
    hello-client/http-api: [ hello-server/http-api, some-other-server/http-api ]

外部端点#

在某些应用程序中，一些客户端微服务可能希望连接到不属于应用程序的服务/端点。例如，该服务可能在外部托管。

为此，UCS 提供了一个伪微服务 ucf.svc.external-endpoint，可以将其添加到应用程序中。它有一个名为 endpoint 的 入口 (Ingress) 端点，客户端微服务的 出口 (Egress) 端点可以连接到该端点。

以下显示了在 UCS 应用程序中使用伪微服务 ucf.svc.external-endpoint 的示例

components:
- name: hello-client
  type: ucf.svc.hello-client

- name: hello-server
  type: ucf.svc.external-endpoint
  parameters:
      service: 10.123.2.123
      port: 8080

connections:
    hello-client/http-api: hello-server/endpoint

当 ucf.svc.external-endpoint 是连接的一部分时，不执行连接验证。hello-server 组件的唯一工作是在客户端微服务 hello-client 上设置服务地址 10.123.2.123 和端口 8080。