当使用OpenAPI时，开发者常常面临一个难题：如何自定义API的输入和输出数据参数和格式，来满足特定业务场景的需求？如果你也曾经感到烦恼，那么不用担心，OpenAPI插件扩展为您提供了一种强大的解决方案，帮助您自定义序列化和反序列化类，轻松适应业务需求，而且无需复杂的代码修改。

这篇文章将带你深入了解如何运用OpenAPI插件扩展，为你的API提供个性化定制，从而提高效率，实现更多可能性。

适用版本

金蝶云·苍穹V5.0.018及以上

功能速览

场景一：反序列化入参

在进行传参时，可能存在请求头Content-Type类型为Text/plain，即入参为text文本，但OpenAPI暂没对这种类型的入参进行处理，那么此时我们可以编写反序列化插件进行入参的反序列化，拿到反序列化后的入参后，也可以对入参进行干预。

接下来，以保存操作API为例，介绍如何进行入参的反序列化。

图 1 保存操作API

步骤一：编写反序列化插件，类中需实现对应接口

操作	接口	重写方法
反序列化	kd.bos.openapi.api.plugin.ApiDeserializerPlugin	deserializer

该方法中，request即为还没反序列化的原入参，处理逻辑是将原Text/plain类型的入参反序列化为map，然后进行入参干预处理，最后返回这个map给OpenAPI进行处理。

import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import kd.bos.openapi.api.plugin.ApiDeserializerPlugin;
import kd.bos.openapi.common.constant.MediaType;
import java.util.Map;
public class DemoApiDeserializerPlugin implements ApiDeserializerPlugin {
  private static final long serialVersionUID = 4568461229506221705L;
  @Override
  public Map<String, Object> deserializer(String request, String contentType) {
    try {
      if(contentType.equals(MediaType.TEXT_PLAIN)){
        //请求的text/plain类型反序列化为Map
        Map<String, Object> map = new ObjectMapper().readValue(request, new TypeReference<Map<String, Object>>() {});
        //干预入参
        Map<String, Object> data = (Map<String, Object>) map.get("data");
        data.put("billno","unittest-001");
        return map;
      }else if(contentType.equals(MediaType.APPLICATION_XML)){
        //XML格式反序列化逻辑
        return ...;
      }else {
        return ...;
      }
    } catch (JsonProcessingException e) {
      throw new RuntimeException(e);
    }
  }
}

步骤二：注册并启用插件

图 2 注册插件

步骤三：测试API

可以看到，传Text文本时正常能正常解析入参并返回保存结果。

图 3 测试反序列化入参

场景二：序列化出参

在实际的业务场景中，标准接口的返回结果可能不满足实际需求，如用操作API查询某单据时，想再添加别的一些字段信息。或者想更改标准的返回日期格式或返回的数据结构信息等，那么此时我们可以编写序列化插件对出参进行个性化处理。

以查询操作API为例，序列化出参操作步骤如下：

图 4 查询操作API

步骤一：编写插件，重写serialize方法

操作	接口	重写方法
序列化	kd.bos.openapi.api.plugin.ApiSerializerPlugin	serialize

其中参数response为还没序列化的原出参，这里逻辑是取标准接口返回中的rows字段信息放到自定义的返回结构中，同时加上自定义的参数和修改返回的日期格式。

import com.alibaba.fastjson.JSON;
import com.alibaba.fastjson.serializer.SerializerFeature;
import kd.bos.openapi.api.plugin.ApiSerializerPlugin;
import kd.bos.openapi.api.plugin.SerializerResult;
import kd.bos.openapi.api.result.ApiQueryResult;
import kd.bos.openapi.common.constant.MediaType;
import kd.bos.openapi.common.result.OpenApiResult;
import java.io.Serializable;
import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Collections;
import java.util.List;
import java.util.Map;
public class DemoApiSerializerPlugin implements ApiSerializerPlugin {
    private static final long serialVersionUID = 1747368553053757065L;
    @Override
    public SerializerResult serialize(Object response, String accept, String contentType) {
        if (contentType.equals(MediaType.APPLICATION_JSON)) {
            OpenApiResult result = (OpenApiResult) response;
      ApiQueryResult data = (ApiQueryResult) result.getData();
            List<Map<String, Object>> rows = data != null ? data.getRows() : Collections.emptyList();
            for (Map<String, Object> row : rows) {
              //往查询结果的rows返回参数中，添加自定义的返回字段信息
                row.put("cusField", "自定义字段信息");
                //更改其中日期格式
                DateFormat format = new SimpleDateFormat("MM/dd/yyyy");
                Object createtime = row.get("createtime");
                String newCreatetime = format.format(createtime);
                row.put("createtime",newCreatetime);
            }
            //自定义结构返回
            MyResult myResult = new MyResult(rows,"200");
            //此处序列化成JSON格式返回,也可根据实际需求返回不同格式返回参数，如文本、xml格式
      Return new SerializerResult(MediaType.APPLICATION_JSON, JSON.toJSONString(myResult, SerializerFeature.PrettyFormat));
        }
        //其他类型的序列化返回
        return null;
    }
    class MyResult implements Serializable{
        private Object datas;
        private String code;
        public MyResult(Object data, String code) {
            this.datas = data;
            this.code = code;
        }
        public Object getData() {
            return datas;
        }
        public void setData(Object data) {
            this.datas = data;
        }
        public String getCode() {
            return code;
        }
        public void setCode(String code) {
            this.code = code;
        }
    }
}

步骤二：注册插件并测试

图 5 测试序列化出参

亮点价值

亮点一：增强数据互通性

OpenAPI插件扩展使您能够针对不同应用程序、平台或第三方系统的要求自定义数据格式，提高了数据的互通性，轻松应对特定业务场景，不再受限于标准数据格式，从而提高数据处理的灵活性。

亮点二：降低维护成本

定制数据处理逻辑通过插件扩展实现，不涉及核心代码的修改，降低了维护成本，避免了因升级API而需要重新编写自定义代码的繁琐工作，从而提高了可维护性。

划重点

• 序列化和反序列化插件支持所有类型的API，包含操作API和自定义API；

• 每个API中只能注册各一个序列化和反序列插件。

#往期推荐#

# 扩展插件，一招让你的操作API更灵活！

# 苍穹OpenAPI数据脱敏，保障企业隐私安全

# 助力集成开发，一文解锁API文档功能

# 一文带你了解苍穹OpenAPI国际化多语言解决方案

更多精彩内容，“码”上了解！↓

还不会自定义OpenAPI出入参？快看这篇锦囊妙计！

还不会自定义OpenAPI出入参？快看这篇锦囊妙计！

恭喜您！