本文以实际场景为例介绍接入HSF协议开放RESTful协议，以帮助您深入理解开放服务。

背景信息

本文仅介绍在实际场景中接入HSF协议开放RESTful服务时一些重要的配置步骤和参数，如需了解完整的流程和参数解释，请参见发布后端已有服务。

调用CSB开放服务时，支持多种请求方式，请根据实际场景选择：
  • 公开访问（无需订购）的服务。
    • curl
      #使用Path传值
curl -H'Content-Type:x-www-form-urlencoded' --data "${Body参数}" "http://CSB服务地址:8086/${服务版本}/${服务名称}/开放Path?Query参数"

#使用query传值
curl --data "${Body参数}" "http://CSB服务地址:8086/开放Path?_api_name=${服务名称}&_api_version=${服务版本}&Query参数"

#使用Header传值
curl -H"_api_name:${服务名称}" -H"_api_version:${服务版本}" --data "${Body参数}" "http://CSB服务地址:8086/开放Path?Query参数"
    • CSB SDK
      #非JSON请求。
java -jar http-client.jar -api ${服务名称} -version ${服务版本} -D'param1=value1' -D'param2=value2' -url http://CSB服务地址:8086/开放Path

#JSON请求。
java -jar http-client.jar -api ${服务名称} -version ${服务版本} -cbJSON "${JSONBody}" -url http://CSB服务地址:8086/开放Path
  • 非公开访问（需要订购）的服务。
    在CSB SDK的基础上增加-ak '${访问凭证ak}' -sk '${访问凭证sk}'。
    #非JSON请求。
java -jar http-client.jar -api ${服务名称} -version ${服务版本} -ak ${访问凭证ak} -sk ${访问凭证sk} -D'param1=value1' -D'param2=value2' -url http://CSB服务地址:8086/开放Path

#JSON请求。
java -jar http-client.jar -api ${服务名称} -version ${服务版本} -ak ${访问凭证ak} -sk ${访问凭证sk} -cbJSON "${JSONBody}" -url http://CSB服务地址:8086/开放Path

FORM

说明 FORM场景，接入HSF协议支持开放为RESTful和WebService协议。
服务配置接入协议-设置入参和出参

接入后端代码

public ResultDTO<Item> add(Item item);

调用服务

您可以选择以下任一请求代码调用CSB开放的服务： 
  • #通过Header参数curl CSB服务。
curl -H "_api_name:item.hsf.add" -H "_api_version:1.0.0" \
-d 'item={"itemName":"benz","quantity":10}' http://csb.target.server:8086/CSB
  • #使用CSB-SDK请求CSB服务
java -jar httpclient.jar -api item.hsf.add -version 1.0.0 -method post \
-D 'item={"itemName":"benz","quantity":10}' -url http://csb.target.server:8086/CSB

请求结果

{
    "body": {
        "msg": "SUCCESS",
        "result": {
            "itemName": "benz",
            "trace": {
                "traceId": "0ba783c115673295906521002d****",
                "requestId": "0ba783c115673295902731001d****",
                "rpcId": "0.1"
            },
            "quantity": 12
        },
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115673295906521002d****"
}

JSON

说明 JSON场景，接入HSF协议只支持开放为RESTful协议；且还需要CSB Broker的版本大于等于3.8.1。
服务配置接入协议-JSON请求-设置入参和出参

接入后端代码

public ResultDTO<Item> add(Item item);

调用服务

#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api item.hsf.add.json -version 1.0.0 -method post \
-cbJSON '{"item":{"itemName":"benz","quantity":10}}' \
-url http://csb.target.server:8086/CSB

请求代码

{
    "body": {
        "msg": "SUCCESS",
        "result": {
            "itemName": "benz",
            "trace": {
                "traceId": "0ba783c115673295906521002d****",
                "requestId": "0ba783c115673295902731001d****",
                "rpcId": "0.1"
            },
            "quantity": 12
        },
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115673295906521002d****"
}

参数MAP（CSB服务和后端代码均未指定Map.Value类型）

服务配置服务配置-参数MAP

接入后端代码

@Override
public <T> ResultDTO<List<T>> addMap(Map<String, T> param) {
    return ResultDTO.getSuccessResult(param.values().stream().collect(Collectors.toList()));
}

调用服务

说明 CSB服务和后端代码均未指定Map.Value类型，可通过JSON class转换为HSF对应参数；不指定class无法转换为指定T，此时T为JSONObject。 
#使用CSB SDK请求CSB服务。 
java -jar httpclient.jar -api map.hsf.add -version 1.0.0 -method post \
-D 'param={
    "jack": {
       "name": "jack",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "江苏",
                "city": "南京"
            },
            "PresentAddress": {
                "province": "北京",
                "city": "北京"
            }
        },
        "class":"com.alibaba.edas.carshop.itemcenter.Contact"
    },
    "lucy": {
        "name": "lucy",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "河北",
                "city": "唐山"
            },
            "PresentAddress": {
                "province": "广东",
                "city": "深圳"
            }
        },
        "class":"com.alibaba.edas.carshop.itemcenter.Contact"
    }
}' -url http://localhost:8086/CSB

请求结果

{
    "body": {
        "msg": "SUCCESS",
        "result": [{
            "name": "lucy",
            "details": {
                "NativePlace": {
                    "province": "河北",
                    "city": "唐山",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "广东",
                    "city": "深圳",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }, {
            "name": "jack",
            "details": {
                "NativePlace": {
                    "province": "江苏",
                    "city": "南京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "北京",
                    "city": "北京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }],
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115679524648981002d88dd"
}

参数List<Map>（CSB服务和后端代码均未指定Map.Value类型）

服务配置参数List-服务配置

接入后端代码

@Override
public <T> ResultDTO<List<T>> addMapList(List<Map<String, T>> params) {
    return ResultDTO.getSuccessResult(params.stream().map(x -> x.values()).flatMap(x -> x.stream()).collect(Collectors.toList()));
}
调用服务
说明 CSB服务和后端代码均未指定Map.Value类型，可通过JSON class转换为HSF对应参数；不指定class无法转换为指定T，此时T为JSONObject。 
#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map.hsf.adds -version 1.0.0 -method post \
-D 'params=[{
    "jack": {
        "name": "jack",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "江苏",
                "city": "南京"
            },
            "PresentAddress": {
                "province": "北京",
                "city": "北京"
            }
        },
        "class":"com.alibaba.edas.carshop.itemcenter.Contact"
    },
    "lucy": {
        "name": "lucy",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "河北",
                "city": "唐山"
            },
            "PresentAddress": {
                "province": "广东",
                "city": "深圳"
            }
        },
        "class":"com.alibaba.edas.carshop.itemcenter.Contact"
    }
}, {
    "lily": {
        "name": "lily",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "江苏",
                "city": "南京"
            },
            "PresentAddress": {
                "province": "北京",
                "city": "北京"
            }
        },
        "class":"com.alibaba.edas.carshop.itemcenter.Contact"
    }
}]' -url http://localhost:8086/CSB

请求结果

{
    "body": {
        "msg": "SUCCESS",
        "result": [{
            "name": "lucy",
            "details": {
                "NativePlace": {
                    "province": "河北",
                    "city": "唐山",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "广东",
                    "city": "深圳",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }, {
            "name": "jack",
            "details": {
                "NativePlace": {
                    "province": "江苏",
                    "city": "南京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "北京",
                    "city": "北京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }, {
            "name": "lily",
            "details": {
                "NativePlace": {
                    "province": "江苏",
                    "city": "南京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "北京",
                    "city": "北京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }],
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115679526561641002d8d2f"
}

参数MAP（后端服务指定Map.Value类型）

服务配置参数MAP-指定MAP.Value-服务配置

接入后端代码

指定Map.Value类型。

@Override
public ResultDTO<List<Contact>> addMapFixedValType(Map<String, Contact> param) {
    return ResultDTO.getSuccessResult(Lists.newArrayList(param.values()));
}

调用服务

#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map.hsf.add.fixtype -version 1.0.0 -method post \
-D 'param={
    "jack": {
        "name": "jack",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "江苏",
                "city": "南京"
            },
            "PresentAddress": {
                "province": "北京",
                "city": "北京"
            }
        }
    },
    "lucy": {
        "name": "lucy",
        "age": 10,
        "details": {
            "NativePlace": {
                "province": "山西",
                "city": "太原"
            },
            "PresentAddress": {
                "province": "浙江",
                "city": "杭州"
            }
        }
    }
}' -url http://localhost:8086/CSB

请求结果

{
    "body": {
        "msg": "SUCCESS",
        "result": [{
            "name": "lucy",
            "details": {
                "NativePlace": {
                    "province": "山西",
                    "city": "太原",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "浙江",
                    "city": "杭州",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }, {
            "name": "jack",
            "details": {
                "NativePlace": {
                    "province": "江苏",
                    "city": "南京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "北京",
                    "city": "北京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        }],
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115679539733771002dabe8"
}

参数POJO.Map

服务配置参数POJO.map-服务配置

接入后端代码

package com.alibaba.edas.carshop.itemcenter;

import java.util.Map;

@Data
public class Contact extends JsonClass {
    private String name;
    private int age;
    private Map<String, Detail> details;
}

@Data
class Detail extends JsonClass {
    private String province;
    private String city;
    private String area;
    private String address;
}

public ResultDTO<Contact> addMapField(Contact contact) {
    return ResultDTO.getSuccessResult(contact);
}

调用服务

#使用CSB SDK请求CSB服务。
java -jar httpclient.jar -api map-field.hsf.add -version 1.0.0 -method post \
-D 'contact={
    "name": "jack",
    "age": 10,
    "details": {
        "NativePlace": {
            "province": "江苏",
            "city": "南京"
        },
        "PresentAddress": {
            "province": "北京",
            "city": "北京"
        }
    }
}' -url http://localhost:8086/CSB

请求结果

{
    "body": {
        "msg": "SUCCESS",
        "result": {
            "name": "jack",
            "details": {
                "NativePlace": {
                    "province": "江苏",
                    "city": "南京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                },
                "PresentAddress": {
                    "province": "北京",
                    "city": "北京",
                    "class": "com.alibaba.edas.carshop.itemcenter.Detail"
                }
            },
            "class": "com.alibaba.edas.carshop.itemcenter.Contact",
            "age": 10
        },
        "code": "0"
    },
    "code": 200,
    "message": "SUCCESS",
    "requestId": "0ba783c115679538866181002da9ae"
}