服务发布规范定义了服务发布中的命名规则、协议选择和映射关系,以及其他的一些规范信息。

命名规范

  • 服务组名称:只允许使用中英文字符、数字及“-”,“_”。不允许有空格。
  • 服务全名:不可以为中文,只能使用数字,字母或“-”。
  • 服务版本:不可以为中文,只能使用数字,字母或 .
  • 服务发布的参数名:只能使用数字,字母或“_”。

协议转换种类

CSB 支持常用协议服务的接入和开放(HTTP/HSF/Web Service/Dubbo/JDBC),可扩展支持定制化的协议转换。

  • 服务接入:在 CSB 上注册某个服务并且提供足够的信息让 CSB 可以访问这个已有的服务。
  • 服务开放:把一个已接入的服务在某个 CSB 实例上提供对应不同协议的 API 调用入口。

缺省支持的服务接入、开放协议如下表所示:

支持的接入协议类型 对应支持的协议开放类型
HTTP Restful API、HTTP OpenAPI、Web Service
HSF HTTP OpenAPI、Web Service、HSF 级联
Web Service HTTP OpenAPI、Web Service 级联
Dubbo HTTP OpenAPI、Web Service
JDBC HTTP OpenAPI
  • CSB 支持数组、列表、集合类型的服务参数,也可以定义复杂的多级参数结构,其它特别的支持情况请参见CSB 接入规范和限制
  • 在协议转换外,CSB 还支持接入接口和开放接口的参数映射、是否可选、缺省值以及在开放接口上是否可见的设置。还将支持定制开发的参数映射机制(Groovy 脚本)。
  • CSB 暂不支持 OAuth 2.0 开放标准。

CSB 接入规范和限制

开放 > 接入协议对 接入规范/限制明细
HTTP > HTTP
  • 支持 GET/PUT/POST/DELETE
  • 参数传递
    • Query:Key-Value 形式
    • Body:Key-Value/JSON/byte[] 形式
  • 支持 RESTful 风格的接入,如 http://localhost:9090/aaa/{userId}/test
  • 支持 HTTP 返回结果透传,不做任何变换加工。
HTTP > Dubbo
  • 支持特别指定注册中心或使用默认注册中心。
  • 支持开放一个接口某个指定方法。
  • 支持 Dubbo 和 Hessian 序列化协议。
  • 支持简单数据类型泛型的 HashMap。
  • 返回结果固定为 JSON 格式。
HTTP > Web Service
  • 支持两种格式的用户名密码接入 SOAP Header。
    • Authorization 类型
    • WSSE 类型
  • 不支持 WSS 和 Policy 等相关的安全和加密处理。
  • 对于 anytype 参数类型,参数定义时要经过特殊定义为 ws:anyType 或者 java.lang.Object
  • 接入后端 WS 服务方法必须是同步的,不支持异步。
  • 支持的 bindTypeDocument-Literal (Wrapper or Unwrapper)
  • 返回结果是将 SOAP XML 转化为 JSON 格式。
HTTP->HSF 支持开放一个接口某个指定方法
  • 支持 java.util.Map 参数。
  • 返回结果固定为 JSON 格式。
Web Service > Web Service
  • 支持 MTOM 等附件数据传输方式的调用。
  • 支持透传式调用后端接入服务。
  • 需要使用 CSB 提供的 WS Client SDK(目前有 Java 版本)传递 Accesskey 和 signature 等相关 Header 信息。
Web Service > HTTP/Dubbo/HSF
  • 相应服务会以 SOAP 1.1的格式发布成一个 Web Service 并提供标准的 WSDL。
  • 需要使用 CSB 提供的 WS Client SDK(目前有 Java 版本)传递 Accesskey 和 signature 等相关 Header 信息。
  • 暂不支持入参的可选和默认值设置。

服务控制

  • 支持具体用户消费凭证到具体服务的访问限流设置。
  • 支持实例级(即服务器级)的总体访问流量保护。
  • 支持实例级(即服务器级)和服务级的基于IP的黑白名单设置。

服务发布

提供版本管理和基本的服务(API)组织管理,支持跨 CSB 实例联动发布。

  • API 服务发布的接入和开放协议,缺省支持的情况请参见协议转换种类的协议类型支持列表。
  • 支持 API 服务分组,用以实现对所发布服务的基本组织分类。
  • 支持 API 服务多版本,可指定变更当前的激活版本。
  • 支持 API 服务的启用、停用、注销、定义变更等基本生命周期管理。
  • 支持 API 服务基于 IP 的黑白名单设置。
  • 支持指定 API 服务每秒最大调用量。
  • 支持指定无需授权审批,申请即可自动授权的自由调用模式。
  • 支持基于路由选择的服务发布,可以根据接入参数的取值不同决定接入的实际协议或地址。
  • 支持 API 服务的级联发布,即可以在一个 CSB 实例上接入服务,可能途径其它中间 CSB 实例,然后在另一个目标 CSB 实例上开放出来,消费方应用直接访问目标 CSB 实例即可。
  • 支持对已发布 API 服务的级联扩展,例如在 A 实例接入 B 实例开放的 API,可以再次指定在实例 C 上开放,服务级联链路按规则自动适配。

CSB 发布的服务的端口说明

  1. CSB 发布出的 Restful 服务的地址访问格式: http://CSB服务地址:8086/CSB

    • CSB 服务地址即创建该实例时绑定的 SLB 的地址。
    • 默认的访问端口为 8086
    • 请求的 context-path 可以任意指定,默认使用 CSB
  2. 根据 CSB 的设计约定,当 CSB 开放成 WebService 服务时,对应的 WSDL 的地址为以下格式:

    • 如果接入是 HTTP 协议,则开放出的 WSDL 地址是:

      http://CSB服务地址:9081/$api_name/$api_version/ws2restful?wsdl
      • CSB 服务地址即创建该实例时绑定的 SLB 的地址。
      • $api_name 为发布的服务名。
      • $api_version 为发布的服务版本。
      • ws2restful 为固定值。
    • 如果接入是 HSF 协议, 则开放出来的 WSDL 地址是:
      http://CSB服务地址:9081/$api_name/$api_version/$method?wsdl
      • CSB 服务地址即创建该实例时绑定的 SLB 的地址。
      • $api_name 为发布的服务名。
      • $api_version 为发布的服务版本。
      • $method 为发布服务时对应的接入方法名。
    • 如果接入是 WS 协议(即WS透传), 则开放出来的 WSDL 地址是:
      http://CSB服务地址:9081/$api_name/$api_version/ws2ws?wsdl            
      • CSB 服务地址即创建该实例时绑定的 SLB 的地址。
      • $api_name 为发布的服务名。
      • $api_version 为发布的服务版本。
      • ws2ws 为固定值。

CSB服务的调用返回约定

调用由 CSB 发布的 HTTP 服务时,如果发生调用错误,则默认返回值是一个如下的 JSON 格式:

{
 "code":500,
 "message":"[503]service not registed, key is : _api_PING_null_null_vcsb",
 "requestId":"1e1eb5d215059677158731001d3d47"
 }