端点
在 UCS 中，端点是微服务的通信接口。UCS 将端点分为两种类型
Ingress 端点 - 通信接口的服务端，即微服务中监听连接的服务器。
Egress 端点 - 通信接口的客户端，即微服务中发起与服务器连接的客户端。
UCS 端点与 server 和 client 角色相关，而非数据流方向。因此，Egress 端点连接到 Ingress 端点。
Egress 端点本质上是虚拟的。但是，它们有一个重要的作用，即表示微服务依赖和连接的外部端点/API。它们还用于抽象客户端微服务中的连接详细信息（address 和 port），如 创建微服务 中所述。在 UCS 应用程序中，当客户端微服务的 Egress 端点连接到 Ingress 端点时，Ingress 端点的连接详细信息（address 和 port）将在应用程序构建期间设置在客户端微服务上。
由于上述抽象
客户端微服务在微服务开发期间不需要预先知道 Ingress 端点的连接详细信息。因此，微服务可以独立开发。
实现 Ingress 端点的微服务可以很容易地被另一个实现类似兼容 Ingress 端点的微服务替换。
对于 UCS 兼容的 微服务，每个 Ingress 或 Egress 端点都附带一个端点定义文件，该文件描述了端点预期的数据交换格式。端点定义文件的格式取决于端点遵循的方案。端点方案在下面部分详细描述。
Ingress 端点
UCS 中的 Ingress 端点使用以下属性描述
字段 |
描述 |
|---|---|
名称 |
Ingress 端点的字符串标识符 |
描述 |
端点的简短描述 |
方案 |
端点遵循的方案 |
数据流 |
通过 Egress 端点的数据流。为 |
服务 |
端点的服务器地址或 Kubernetes 服务抽象名称。 |
端口 |
Ingress 端点的端口号。 |
协议 |
端点必须使用的网络协议。为 |
Egress 端点
UCS 中的 Egress 端点使用以下属性描述
字段 |
描述 |
|---|---|
名称 |
Egress 端点的字符串标识符 |
描述 |
端点的简短描述 |
协议 |
端点必须使用的网络协议。为 |
方案 |
端点遵循的方案 |
强制性 |
布尔值，指示连接 Egress 端点对于微服务正常工作是否是强制性的 |
数据流 |
通过 Egress 端点的数据流。为 |
UCS 端点方案
HTTP
由字符串枚举 http 表示。它用于使用 HTTP 协议进行通信的端点。
HTTP 端点方案的端点定义文件必须遵循 OpenAPI v3.0.3 规范 - https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md。该文件可以是 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 规范 - https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md 该文件可以是 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": "https://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 表示。它用于使用异步事件通过 Redis over RESP (REdis Serialization Protocol) 进行通信的端点。RESP 端点方案的端点定义文件必须遵循 AsyncAPI v2.2.0 规范 - https://github.com/asyncapi/spec/blob/v2.2.0/spec/asyncapi.md 该文件可以是 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": "https://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。