可配置输入参数的接口如何设计

发表于 2024-03-06 更新于 2024-03-07 阅读次数：本文字数： 1.7k 阅读时长 ≈ 6 分钟

个人博客：无奈何杨（wnhyang）

个人语雀：wnhyang

共享语雀：在线知识共享

Github：wnhyang - Overview

作为程序员，我们绝大多数场景需要根据业务需求来设计系统，开发后端接口，这些接口通常都是在设计阶段就确定了，但是还有一些场景需要实现支持的配置的接口，包含以下功能

1、可以配置接口url

这个通常在一些论坛博客类系统中比较常见，用于设置个人主页，但其实这个又是不同概念，个人主页通常是get请求，然后通过path索引用户主页。

2、可选择接口具体实现

流程引擎、规则引擎通常就可以实现

3、输入参数和输出参数可配置

应用场景包括数据收集等

前面乱讲一通，最终回归本题——可配置输入参数的接口如何设计？

AI的回答

以下是AI的回答——可配置输入参数的接口如何设计？

设计支持可配置输入参数的接口时，主要目标是保证接口的灵活性和易用性，同时兼顾健壮性和可维护性。以下是一个通用的设计策略：

使用Map或Dictionary类型的参数：
可以定义一个Map<String, Object>作为接口的输入参数，其中键（key）表示参数名，值（value）表示参数值。这样可以根据需要动态添加或减少参数。

1
2
3

public interface MyService {
    Response handleRequest(Map<String, Object> parameters);
}

这种方法简单灵活，但对于复杂的参数校验和类型转换需要额外处理。

使用泛型请求类：
定义一个包含所有可能参数的请求类，使用Java Bean或者Builder模式，通过构造方法或setters注入参数，同时可以用@JsonCreator或@AllArgsConstructor等注解支持JSON序列化和反序列化。

public class RequestParams<T> {
    private String param1;
    private int param2;
    private T customParam; // 泛型参数，可根据需求定制
     
    // 构造方法、getter、setter省略...

    // 或者使用Builder模式
    public static class Builder<T> {
        // ...
        public RequestParams build() { /*...*/ }
    }
}

public interface MyService {
    Response handleRequest(RequestParams<?> params);
}

使用策略模式：
如果参数的处理方式因参数类型而异，可以设计不同的策略类处理不同类型的参数，接口接收这些策略类作为参数。

public interface ParamStrategy {
    void process(RequestContext context);
}

public interface MyService {
    Response handleRequest(List<ParamStrategy> strategies);
}

使用命令模式：
对于复杂的操作，可以将参数封装成一个命令对象，命令对象包含所有执行操作所需的参数。

public interface Command {
    void execute();
}

public class SomeCommand implements Command {
    private final String param1;
    private final int param2;
    
    public SomeCommand(String param1, int param2) {
        this.param1 = param1;
        this.param2 = param2;
    }

    @Override
    public void execute() {
        // 使用param1和param2执行操作
    }
}

public interface MyService {
    Response handleRequest(Command command);
}

在设计时，请务必充分考虑参数的有效性检查、默认值设定以及错误处理机制，确保接口的健壮性。同时，良好的文档说明对于使用者来说非常重要，特别是当参数众多且复杂时。

实现思路

有了AI的帮助，思路一下子打开了是吧！

这里主要讨论Map作为参数具体该怎么实现。

若仅着眼于数据采集的目标，采用Map作为输入参数无疑是一种可行方案，然而这种方式也存在显著不足。尽管如此便捷，但数据的原始形态较为零散无序，在实际应用前仍需额外进行整理加工，因此从整体效果上看并不尽如人意。

所以还是需要一些设计的，简化流程如下，我讲的不好，也可以直接跳到下面demo看实现。

具体实现Demo

Controller

/**
 * @author wnhyang
 * @date 2023/11/29
 **/
@RestController
@RequestMapping("/risk")
@RequiredArgsConstructor
@Slf4j
public class RiskController {

    private final RiskService riskService;
    
    @PostMapping("/{name}/sync")
    public String syncRisk(@PathVariable("name") String name, @RequestBody Map<String, Object> params) {

        log.info("syncRisk {}", name);
        log.info("param {}", params);

        return riskService.syncRisk(name, params);
    }
    
}

Service

/**
 * @author wnhyang
 * @date 2023/11/29
 **/
@Service
@Slf4j
@RequiredArgsConstructor
public class RiskServiceImpl implements RiskService {

    /**
     * 模拟服务配置
     */
    private static final Map<String, Set<InputFieldVO>> SERVICE_CONFIG = Map.of(
            "publicInterface", new HashSet<>(Arrays.asList(
                    new InputFieldVO().setId(1L).setParamName("eventId").setDisplayName("事件标识").setName("N_S_eventId").setRequired(true).setType(0),
                    new InputFieldVO().setId(2L).setParamName("appName").setDisplayName("应用标识").setName("N_S_appName").setRequired(true).setType(0),
                    new InputFieldVO().setId(3L).setParamName("customerId").setDisplayName("客户号").setName("N_S_customerId").setRequired(true).setType(0),
                    new InputFieldVO().setId(5L).setParamName("age").setDisplayName("年龄").setName("N_N_age").setRequired(true).setType(1),
                    new InputFieldVO().setId(4L).setParamName("money").setDisplayName("金额").setName("N_F_money").setRequired(true).setType(2),
                    new InputFieldVO().setId(6L).setParamName("transTime").setDisplayName("交易时间").setName("N_D_transTime").setRequired(true).setType(3),
                    new InputFieldVO().setId(7L).setParamName("transType").setDisplayName("交易类型").setName("N_E_transType").setRequired(true).setType(4),
                    new InputFieldVO().setId(8L).setParamName("isPayee").setDisplayName("是否收款人").setName("N_B_isPayee").setRequired(true).setType(5),
                    new InputFieldVO().setId(9L).setParamName("event").setDisplayName("事件标识").setName("N_S_event").setRequired(true).setType(0)
            )));

    @Override
    public String syncRisk(String name, Map<String, Object> params) {

        // 通过SERVICE_CONFIG取name判空
        log.info("name {}", name);
        log.info("params {}", params);

        Set<InputFieldVO> fields = SERVICE_CONFIG.get(name);
        if (fields == null) {
            return "服务未找到";
        }
        // 使用增强for循环代替迭代器
        for (InputFieldVO field : fields) {
            Object value = params.get(field.getParamName());
            if (value != null) {
                // 设置field的值
                field.setValue(value);
                log.info("field {}", field);
            }
        }

        return fields.toString();
    }

    @Override
    public String asyncRisk(String name, Map<String, Object> params) {
        log.info("name {}", name);

        return null;
    }
}

InputFieldVO

@Data
@AllArgsConstructor
@NoArgsConstructor
@Builder
public class InputFieldVO {

    /**
     * 参数名
     */
    private String paramName;

    /**
     * 是否必填
     */
    private Boolean required;

    /**
     * 值，默认null
     */
    private Object value;

    /**
     * 自增编号
     */
    private Long id;

    /**
     * 显示名
     */
    private String displayName;

    /**
     * 字段名
     */
    private String name;

    /**
     * 字段类型
     */
    private Integer type;

    /**
     * 字段分组
     */
    private Long groupId;

    /**
     * 描述
     */
    private String description;

    /**
     * 默认值
     */
    private String defaultValue;

    /**
     * 是否动态字段 N（normal）和D（dynamic）
     */
    private Boolean dynamic = Boolean.FALSE;

}

FieldTypeEnum

/**
 * @author wnhyang
 * @date 2023/12/5
 **/
@AllArgsConstructor
@Getter
public enum FieldTypeEnum {

    /**
     * 字符型
     */
    STRING(0, "S", "字符型"),

    /**
     * 整数型
     */
    NUMBER(1, "N", "整数型"),

    /**
     * 小数型
     */
    FLOAT(2, "F", "小数型"),

    /**
     * 日期型
     */
    DATE(3, "D", "日期型"),

    /**
     * 枚举型
     */
    ENUM(4, "E", "枚举型"),

    /**
     * 布尔型
     */
    BOOLEAN(5, "B", "布尔型");


    private final Integer code;

    private final String name;

    private final String desc;

}

测试

请求http://localhost:8080/risk/publicInterface/sync

{
  "eventId": "手机交易",
  "appName": "手机",
  "customerId": "123456",
  "age": "24",
  "money": "3.14159",
  "transTime": "2024-03-01 20:35:45",
  "transType": "2",
  "isPayee": "true",
  "event": "true"
}