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

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

个人语雀：wnhyang

共享语雀：在线知识共享

Github：wnhyang - Overview

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

1、可以配置接口url

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

2、可选择接口具体实现

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

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

应用场景包括数据收集等

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

AI的回答

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

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

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

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;}@Overridepublic 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))));@Overridepublic 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();}@Overridepublic 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"
}