pixiu-http-to-dubbo

name	pixiu-http-to-dubbo
description	Creates and debugs dubbo-go-pixiu HTTP-to-Dubbo route YAML. Use for api_config.yaml/conf.yaml routes, direct Dubbo URLs, registry-backed Dubbo, mappingParams, mapType, parameterTypes, opt.types/opt.values, or generic-invoke errors. Do not use for non-Dubbo HTTP proxy routes or new registry adapter implementation.

pixiu-http-to-dubbo

Purpose

Generate a complete or embeddable api_config.yaml, and add the required companion conf.yaml fragments.

When to use

• Use when:

  • Creating or modifying HTTP-to-Dubbo routes, including registry/direct mode switching, parameter mapping, type conversion, generic-invoke config, or debugging errors such as no provider found, ClassNotFound, empty responses, and signature mismatches.

• Do not use for:

  • New registry adapter implementation or non-Dubbo HTTP proxy routes.

Inputs

Do not generate YAML, write code, create files, or take any implementation action until the user has provided all required inputs. This is a first principle.

If any required input is missing, this turn must only ask for the missing fields in the current input group; do not generate examples, defaults, YAML, code, or final output.

Even if configuration information seems inferable, obvious, or implied by context, you must still ask the user to confirm it. Do not proceed until the user confirms it.

• Choose Dubbo provider mode (required):
  • Required:
    • provider_mode: registry or direct
• listener (required):
  • Defaults:
    • address.socket_address.address: 0.0.0.0
    • address.socket_address.port: 8888
• route_config (required):
  • Defaults:
    • routes[].match.prefix: /api/v1
    • routes[].route.cluster: dubbo-route
• dgp.filter.http.apiconfig (required):
  • Defaults:
    • config.path: configs/api_config.yaml
    • config.dynamic: false
• dgp.filter.http.dubboproxy (required):
  • Defaults:
    • dubboProxyConfig.timeout_config.connect_timeout: 5s
    • dubboProxyConfig.timeout_config.request_timeout: 5s
    • dubboProxyConfig.load_balance: roundrobin
    • dubboProxyConfig.retries: "3"
• api_config.yaml resource/method (required):
  • Required:
    • resources[].path
    • methods[].httpVerb
    • integrationRequest.interface
    • integrationRequest.method
  • Optional:
    • resources[].description
    • integrationRequest.group
    • integrationRequest.version
    • integrationRequest.applicationName
    • integrationRequest.clusterName
  • Defaults:
    • resources[].type: restful
    • resources[].timeout: 1000ms
    • methods[].enable: true
    • methods[].timeout: 1000ms
    • inboundRequest.requestType: http
    • integrationRequest.requestType: dubbo
• Dubbo method parameters (required when the method has parameters):
  • Required:
    • mappingParams[] using exactly one argument style:
      • positional mappings: mappingParams[].mapTo: "0", "1", ...
      • opt.values mappings: map request fields to opt.values, and map or declare Java types separately when needed
  • Conditionally required:
    • opt.types when using opt.values and Java types cannot be inferred or must be explicit.
    • parameterTypes[] for direct-mode positional mappings, or whenever Java types must override inferred types.
    • When method parameters contain POJOs, nested objects, or collections, provide the corresponding Java class names and field types.
• Registry provider (required when provider_mode: registry; defaults use Zookeeper, Nacos can also be chosen, examples below use Zookeeper):
  • Required:
    • dubboProxyConfig.registries.zookeeper.address
  • Optional:
    • dubboProxyConfig.registries.zookeeper.group
    • dubboProxyConfig.registries.zookeeper.namespace
    • dubboProxyConfig.registries.zookeeper.username
    • dubboProxyConfig.registries.zookeeper.password
  • Defaults:
    • dubboProxyConfig.registries.zookeeper.protocol: zookeeper
    • dubboProxyConfig.registries.zookeeper.registry_type: interface
    • dubboProxyConfig.registries.zookeeper.timeout: 3s
    • dubboProxyConfig.registries.zookeeper.group: DEFAULT_GROUP
• Direct provider (required when provider_mode: direct):
  • Required:
    • integrationRequest.url
  • Conditionally required:
    • integrationRequest.parameterTypes (use [] for no-argument methods; required when opt.types is not used)
  • Optional:
    • integrationRequest.protocol (needed when url is host:port; when url has a scheme, it must match that scheme)
  • Defaults:
    • integrationRequest.protocol: dubbo
    • integrationRequest.serialization: hessian2

Workflow

1. Check required Inputs first:
   1. Read existing config and already provided user information first; do not ask again for information already present or stated.
   2. Ask one Inputs group at a time. Each time, output only that group's required fields, with a short explanation after each field.
   3. If the current group's required fields are incomplete, ask only for the missing fields and do not move to the next group.
   4. After the current group's required fields are complete, ask whether to fill that group's optional fields; if yes, list those optional fields with short explanations.
   5. After optional fields are skipped or completed, apply that group's defaults and output default-value information; defaults must not override existing config or user input.
2. Read current source before editing YAML:
   • pkg/config/api_config.go.
   • pkg/filter/http/remote/dubbo_handler.go.
   • pkg/client/dubbo/types.go, pkg/client/dubbo/typeconv.go, and pkg/client/dubbo/dubbo.go.
3. Choose registry or direct path by provider_mode:
   • Registry uses the registry config in dgp.filter.http.dubboproxy.
   • Direct uses integrationRequest.url.
4. Generate api_config.yaml: write resources[].methods[] for each HTTP API, and use either positional mappingParams or opt.values/opt.types to organize Dubbo arguments.
5. Complete conf.yaml: use HCM for route and filters, and ensure dgp.filter.http.apiconfig is before the Dubbo proxy.

Output format

• Show the relevant YAML fragments.

Validation

• When using positional mappings, verify mappingParams[].mapTo indexes match the declared Java type order exactly.
• Verify positional mappings and opt.values are not mixed in the same method.
• Verify dgp.filter.http.apiconfig is ordered before dgp.filter.http.dubboproxy.
• Verify mapType is supported by client/dubbo.MapTypes after normalization against constant.JTypeMapper: lowercase primitives and supported fully-qualified Java type aliases such as java.lang.String/java.lang.Integer are valid; short uppercase aliases such as String/Boolean are not.
• Verify POJO arguments have a class field in the corresponding JSON body, such as {"class":"com.example.User", ...}.

Examples

Direct mode (api_config.yaml):

name: pixiu
description: HTTP facade for Dubbo user service
resources:
  - path: /users/:name
    type: restful
    timeout: 5s
    description: User APIs
    methods:
      - httpVerb: GET
        enable: true
        timeout: 5s
        inboundRequest:
          requestType: http
        integrationRequest:
          requestType: dubbo
          url: dubbo://127.0.0.1:20880
          protocol: dubbo
          serialization: hessian2
          interface: com.example.UserService
          method: getUser
          group: ""
          version: "1.0.0"
          parameterTypes:
            - java.lang.String
          mappingParams:
            - name: 
               
               

Direct mode (conf.yaml):

http_filters:
  - name: dgp.filter.http.apiconfig
    config:
      path: configs/api_config.yaml
      dynamic: false
  - name: dgp.filter.http.dubboproxy
    config:
      dubboProxyConfig:
        timeout_config:
          connect_timeout: 5s
          request_timeout: 5s
        load_balance: roundrobin
        retries: "3"

Registry mode (api_config.yaml):

integrationRequest:
  requestType: dubbo
  interface: com.example.UserService
  method: getUser
  group: ""
  version: "1.0.0"
  parameterTypes:
    - java.lang.String
  mappingParams:
    - name: uri.name
      mapTo: "0"
      mapType: string

Registry mode (conf.yaml):

http_filters:
  - name: dgp.filter.http.apiconfig
    config:
      path: configs/api_config.yaml
      dynamic: false
  - name: dgp.filter.http.dubboproxy
    config:
      dubboProxyConfig:
        registries:
          zookeeper:
            protocol: zookeeper
            address: 127.0.0.1:2181
            timeout: 3s
            group: DEFAULT_GROUP
            registry_type: interface
        timeout_config:
          connect_timeout: 5s
          request_timeout: 5s
        load_balance: roundrobin
        retries: "3"

Minimal positional parameter mapping:

integrationRequest:
  requestType: dubbo
  interface: com.example.UserService
  method: getUser
  parameterTypes:
    - java.lang.String
  mappingParams:
    - name: uri.name
      mapTo: "0"
      mapType: string

Minimal opt.values / opt.types mapping:

integrationRequest:
  requestType: dubbo
  interface: com.example.UserService
  method: getUser
  mappingParams:
    - name: requestBody.values
      mapTo: opt.values
    - name: requestBody.types
      mapTo: opt.types