sgcREST 功能矩阵：REST 服务器与 OpenAPI | eSeGeCe

sgcREST 功能矩阵

sgcREST 的全部能力，对应到 REST 服务器及其配套组件、OpenAPI 服务器引擎和 OpenAPI 客户端家族。每项能力在 Delphi 和 C++ Builder 中的表现完全一致，每份授权都提供完整源代码。本次发布尚未提供各组件的独立子页面，以下每一项内容都直接呈现在本页上。

REST 服务器

CORS、统计、租户与用户

OpenAPI 服务器

规范优先与代码优先

OpenAPI 客户端

调用任何以 OpenAPI 描述的 API

标准与平台

Delphi 7 至 13，C++ Builder

sgcREST 是自包含的。它内置了 sgcWebSockets Core 运行时，因此它不是附加组件，并且运行在 RAD Studio 自带的标准 Indy 库之上。

代码优先 OpenAPI 需要 Delphi XE7 或更高版本。从带特性标注的 Delphi 类生成规范依赖于 XE7 引入的 RTTI。REST 服务器、其配套组件以及规范优先 OpenAPI 引擎则可以在 Delphi 7 到 13 上运行。

组件

七个类，三个家族

SGC REST 面板页上的四个组件，以及三个纯代码的 OpenAPI 服务器和客户端类，声明在 sgcHTTP_REST_Server* 和 sgcHTTP_OpenAPI_* 单元中。

组件类是否在面板上描述
REST 服务器TsgcHTTPRESTServer是构建在 TsgcHTTPServer 之上的 REST API 服务器，带 CORS 处理以及可挂载的统计/租户配套组件。
REST 服务器统计TsgcHTTPServerStats是请求计数、延迟跟踪、Prometheus 格式的 /metrics 和 JSON 格式的 /health。
REST 服务器租户TsgcHTTPServer_Tenancy是按主机、路径、请求头或 JWT 声明解析多租户。
REST 服务器用户TsgcHTTPServer_Users是本地账户存储：添加、验证、哈希、角色标签和持久化用户。
OpenAPI 服务器，规范优先TsgcOpenAPIServerHandler否，纯代码根据已加载的 OpenAPI 3.0/3.1 文档提供 API 服务，并带请求校验。
OpenAPI 服务器，代码优先TsgcOpenAPICodeFirstScanner否，纯代码根据带 RTTI 特性标注的 Delphi 类生成 OpenAPI 规范。需要 Delphi XE7+。
OpenAPI 客户端TsgcOpenAPI_Client否，纯代码适用于任何 OpenAPI 描述端点的通用运行时客户端。
REST 服务器

CORS、统计、租户与用户存储

TsgcHTTPRESTServer 是 TsgcHTTPServer 的派生类，因此它从每个 sgc HTTP 服务器共用的相同绑定和 TLS 处理起步，并在此之上叠加了 REST API 常见的附加能力。

能力API说明
CORSCORSOptions（Enabled、AllowOrigins、AllowHeaders、AllowMethods）默认关闭。启用后，预检 OPTIONS 请求会被自动应答。
统计配套组件ServerStats: TsgcHTTPServerStats挂载一个统计组件后，每个请求都会被自动计数和计时，无需改动路由处理程序。
租户配套组件Tenancy: TsgcHTTPServer_Tenancy、Tenant挂载一个租户组件来解析调用方所属的租户；Tenant 读取当前请求的解析结果。
请求计数TotalRequests、Status1xx 到 Status5xx位于 TsgcHTTPServerStats。在发送响应时按状态类计数。
延迟LatencyMinMs、LatencyAvgMs、LatencyMaxMs在 TsgcHTTPServerStats 上按请求跟踪，可用 Reset 重置。
指标端点GetMetricsText、IsMetricsRequestPrometheus 文本暴露格式 0.0.4，在 /metrics 上提供。
健康检查端点GetHealthJSON、IsHealthRequest在 /health 上提供的 JSON 健康负载，包含 UptimeSeconds 和 ActiveConnections。
按端点统计GetEndpointStats、Endpoints每个端点一组路径/计数，用于报表或管理控制台。
租户解析Resolution、ResolveTenant位于 TsgcHTTPServer_Tenancy。按主机后缀、路径片段、请求头或 JWT 声明解析。
租户来源HostSuffix、PathSegmentIndex、HeaderName、ClaimName、DefaultTenant为所配置的 Resolution 模式读取的来源，以及未解析出结果时的回退值。
自定义解析OnResolveTenant覆盖或扩展内置的解析逻辑。
用户账户AddUser、DeleteUser、FindUser、ValidateCredentials、SetPassword、EnableUser、UserExists位于 TsgcHTTPServer_Users。加盐哈希凭据，永不以明文返回。
角色AddRole、RemoveRole、UserHasRole、GetUserRoles每个账户的自由格式角色标签，可从路由处理程序中检查。
枚举Count、GetUserCount、GetUserByIndex、GetUsernames用于报表或管理控制台的只读视图；密码哈希和盐值永不包含在内。
持久化LoadUsers、SaveUsers、SaveToFile、LoadFromFile、ExportUsers、ImportUsersStorage.EncryptAtRest 对存储进行加密；OnLoadUsers/OnSaveUsers 可替换为自定义后端。
事件OnStats、OnResolveTenant、OnValidateCredentials、OnFindUser、OnException每个配套组件各有一个事件，用于处理内置逻辑未覆盖的情形。
OpenAPI 服务器

规范优先路由，代码优先生成

两种方式最终都归入同一张路由表和同一个请求上下文；区别只在于 OpenAPI 文档的来源。

能力API说明
路由表TsgcOpenAPIRouteTable（Add、Match）根据规范的 paths 部分构建；将一个动词和一个路径匹配到一个 operationId。
请求上下文TsgcOpenAPIServerContext（Request、Response、PathParams、QueryParams）每个匹配到的请求对应一个实例，请求结束时释放。
带类型的参数PathParamAsString、PathParamAsInteger、QueryParamAsString、QueryParamAsInteger、QueryParamAsBoolean一次调用即可读取并转换一个路径或查询值。
请求体访问BodyAsString、BodyAsJSON、HeaderValue解析请求体一次并缓存结果。
响应RespondJSON、RespondError写入带状态码的 JSON 响应体，或写入结构化的错误负载。
请求生命周期BeforeHandle、AfterHandle、HandleException位于 TsgcOpenAPIServerHandler。可重写以添加日志记录、身份验证检查或自定义错误映射。
校验TsgcOpenAPIJSONValidator根据规范声明的 JSON Schema 校验请求体、查询参数和路径参数。
规范生成GenerateSpec、Title、Description、Version、BasePath位于 TsgcOpenAPICodeFirstScanner。根据带特性标注的类的 RTTI 生成 OpenAPI 3.0 文档。
契约特性sgcServiceContract、sgcRoute、sgcSummary、sgcDescription、sgcTag、sgcResponse用于填充生成规范的类级和方法级特性。
动词特性sgcHttpGet、sgcHttpPost、sgcHttpPut、sgcHttpDelete、sgcHttpPatch、sgcHttpHead、sgcHttpOptions声明带特性标注的方法响应哪个 HTTP 动词。
参数绑定sgcFromPath、sgcFromQuery、sgcFromHeader、sgcFromBody、sgcRequired声明每个方法参数从哪里读取。
分发TsgcOpenAPICodeFirstDispatcher（RegisterController、DispatchOperation、IsRegistered）直接调用为某个 operationId 注册的带特性标注的方法，无需手写 if 链。
依赖Delphi XE7 或更高版本代码优先的扫描和分发依赖 System.Rtti，XE7 之前不可用。规范优先没有这项要求。
OpenAPI 客户端

一个运行时客户端，适用于任何 OpenAPI 描述的 API

适用于任何 OpenAPI 描述端点的通用客户端，内置 Basic 身份验证、Bearer 令牌、通用 OAuth2 和通用 JWT。

能力API说明
基础调用HTTP_REQUEST位于 TsgcOpenAPI_Client。将一对 TsgcOpenAPIRequest/TsgcOpenAPIResponse 发往任意端点。
基础 URLSetBaseURL、GetBaseURL请求中每个相对路径所解析依据的端点。
通用身份验证Authentication（Basic、Token、OAuth2、JWT）Basic 身份验证和 Bearer 令牌，另加通用的 OAuth2 和 JWT 流程。
传输TLSOptions、ProxyOptions、EncodeBodyAsUTF8与 sgc HTTP 技术栈其余部分共用的标准 TLS 和代理配置。
进度与日志OnUpload、OnDownload、Log、LogFileName跟踪较大的请求/响应体，并可选择将每次调用记录到文件。
请求钩子OnBeforeRequest在请求发出之前检查或修改它。
TLS 钩子OnSSLVerifyPeer、OnSSLGetHandler、OnSSLAfterCreateHandler证书校验和处理程序自定义，与 sgc HTTP 技术栈其余部分共用。
标准与平台

API、编译器与目标平台

线路层面采用公开标准，并在每个受支持编译器上使用同一份源代码。

方面细节
OpenAPIOpenAPI 3.0 和 3.1，既用于服务器的规范优先路由，也用于请求校验所依据的 JSON Schema。
客户端身份验证HTTP Basic 身份验证和 Bearer 令牌，另加通用 OAuth2 和 JWT。
指标Prometheus 文本暴露格式 0.0.4，位于 /metrics。
平台全部七个类均支持 Windows Win32、Windows Win64、Linux64、macOS、iOS 和 Android。
依赖除内置的 sgcWebSockets Core 运行时外没有其他依赖。全部七个类都不需要额外的附加组件。
编译器Delphi 和 C++ Builder 7 至 13。代码优先 OpenAPI 需要 Delphi XE7 或更高版本。
版本REST 服务器家族也随 sgcWebSockets Professional 及以上版本提供，OpenAPI 服务器自 Enterprise 起提供，OpenAPI 客户端自 Standard 起提供。
授权独立产品。已内置 sgcWebSockets Core 运行时，并包含完整源代码。
超值之选：All-AccesseSeGeCe 全部产品，含高级支持，每年 €1,059 起。
查看 All-Access 价格

用 sgcREST 构建

下载免费试用版，从 Delphi 或 C++ Builder 搭建您的第一个 REST 端点或发起第一次 OpenAPI 调用。

下载免费试用版 查看价格