有关EAS-BOS二次开发的各类问题（三）：接口开发注意事项&常用调试工具&常见问题的解决方案

EAS-BOS 中结合 WebService 接口开发的一些注意事项

一、接口设计阶段

1. 理解业务需求

   与业务部门充分沟通，明确接口的用途。例如，是用于数据同步（如将外部系统的销售订单数据同步到 EAS 系统），还是用于查询数据（如查询 EAS 系统中的库存信息并返回给外部系统）。这将决定接口的输入输出参数、功能范围等关键要素。

   对业务流程进行详细梳理。以采购订单接口为例，要清楚采购订单从创建、审批、发货到收货整个流程中，接口在每个环节需要提供哪些数据进行交互。

   定义接口规范

   确定接口的协议。Web Service 常用的协议有 SOAP（Simple Object Access Protocol）和 REST（Representational State Transfer）。SOAP 是基于 XML 的协议，比较适合复杂的企业级应用，具有较好的安全性和可靠性；REST 相对更轻量级，使用 HTTP 协议的方法（如 GET、POST、PUT、DELETE）来操作资源，在简单的数据查询和传输场景中效率较高。

   定义接口的输入输出参数。参数的数据类型要明确，比如对于输入的日期参数，要确定是采用日期字符串格式（如 “yyyy - MM - dd”）还是时间戳格式。对于复杂的数据类型，如包含多个子属性的订单对象，要定义好其层次结构和每个子属性的数据类型。例如，订单对象可能包含订单头信息（订单编码、下单日期、库存组织等）和订单分录行信息（物料编码、规则、数量、单价、金额等）。

   
   

   版本控制、可复用规划

   考虑接口的扩展性和兼容性，提前规划接口版本。在接口发生变更时，如新增参数、修改参数的数据类型或功能逻辑发生变化，要能够通过版本号来区分不同的接口实现。例如，接口初始版本为 v1.0，当需要增加一个新的查询条件参数时，可以将版本升级到 v1.1，并在接口文档中详细说明版本变更的内容。

   
   

   如：在某一个项目上，业务需求原本是针对某一个子公司开发的接口，然后在接口设计时只支持该子公司的数据导入导出（发现代码写死直接取该子公司的数据），后客户又提出需求另一个子公司也需要做该接口，所以，如果说我们在接口参数上增加一个“组织”的参数，在第三方调用该接口时，传入相应的组织信息，我们再根据该组织参数进行不同的数据处理返回，这样接口就可以做到可复用。而不用每一个子公司都写一套代码。

   
   

   二、开发阶段

          开发环境搭建：确保金蝶 EAS - BOS 开发环境正确配置。 熟悉金蝶 EAS - BOS 的开发框架。

   
   

         安全机制实现：考虑接口的安全访问。可以采用身份验证机制，对用户权限进行严格控制。在 EAS-BOS 中，可以通过配置角色和权限来限制接口的访问。例如，只有具有 “数据同步管理员” 角色的用户才能调用数据同步接口，防止未经授权的用户对接口进行操作。

        

        异常处理机制

• 构建完善的异常处理机制。在接口开发过程中，可能会遇到多种异常情况，如网络故障、数据库连接异常、数据验证不通过等。对于这些异常，要能够捕获并返回有意义的错误信息给调用方。例如，当校验报文信息时，发现不符合数据规范，返回一个较详细的如“传入数据操作参数<orgNum>为空”、“报文中，number节点不存在”等的错误消息。

• 进行异常测试。通过模拟各种异常情况，如手动断开网络连接、在数据库中插入不符合规则的数据等，来验证异常处理机制的有效性。

三、安全模式调用业务接口案例：

      首先是登录接口，全部整理写在一个login方法中

•   public static WSContext login() {
      WSContext login = null;
      EASLoginProxyProxy easLoginProxyProxy = new EASLoginProxyProxy();
      try {
        properties = new HashMap();
        properties.put("userName", "接口用户名");
        properties.put("password", "对应的接口用户密码");
        properties.put("slnName", "eas");
        properties.put("language", "L2");
        properties.put("dbType", "0"); 
        properties.put("dcName", "数据中心"); 
      properties.put("address", "http://127.0.0.1:6890（接口地址）");
         
        easLoginProxyProxy.setEndpoint(String.valueOf(properties.get("address")) + "/ormrpc/services/EASLogin");
        login = easLoginProxyProxy.login((String)properties.get("userName"), (String)properties.get("password"), 
          (String)properties.get("slnName"), (String)properties.get("dcName"), (String)properties.get("language"), Integer.valueOf((String)properties.get("dbType")).intValue());
        System.out.println("sessionId" + login.getSessionId());
        sap.setEndpoint(String.valueOf(properties.get("address")) + "/ormrpc/services/WSSapAndEasFacade");
      } catch (IOException e) {
        e.printStackTrace();
      }
      return login;
    }

• 用安全模式调用登录接口之后， 调用业务接口（这里以凭证接口为例）

•  WSContext ctx = login();   //调用上面写的登录方法
            if (ctx != null)
            {
            WSWSVoucherSrvProxyServiceLocator locator = new WSWSVoucherSrvProxyServiceLocator();
            WSInsertVoucherLogFacadeSrvProxyServiceLocator logLocator = new WSInsertVoucherLogFacadeSrvProxyServiceLocator();
  
            URL portUrl = new URL("http://127.0.0.1:6890/ormrpc/services/WSWSVoucher");
            URL logPortUrl = new URL("http://127.0.0.1:6890/ormrpc/services/WSInsertVoucherLogFacade");
            WSWSVoucherSrvProxy voucherProxy = locator.getWSWSVoucher(portUrl);
            ((Stub)voucherProxy).setHeader("http://login.webservice.bos.kingdee.com", "SessionId", ctx.getSessionId());
            WSInsertVoucherLogFacadeSrvProxy sapLog = logLocator.getWSInsertVoucherLogFacade(logPortUrl);
            ((Stub)sapLog).setHeader("http://login.webservice.bos.kingdee.com", "SessionId", ctx.getSessionId());
            rtn = importVoucher(voucherProxy, jsonOther);

四、测试阶段

1、接口常用的调试工具有两个：

       soapui工具，主要是调webservice接口

      登录登出接口可参考该篇文章：websevices：标准login\logout接口的使用:https://vip.kingdee.com/link/s/lHJgZ

2、Postman工具主要用于API接口调试，可以发送多种 HTTP 请求，包括但不限于 GET、POST等

• 对于每种请求类型，能够方便地设置请求的详细参数。以 POST 请求为例，可以在请求体（Body）中选择不同的数据格式，如 JSON、XML、form - data 和 x - www - form - urlencoded 等。如下面的职位接口，需要以 JSON 格式发送请求体，通过 Postman 就能轻松地构建这样的请求。

3、对于接口调试小编喜欢用这样的方式，自己新建一个测试类，模拟接口报文，可以做一些不规范的报文 ，比如少某一个参数、数据不符合要求、然后直接在测试类中调试我们的接口，看接口是否能准确捕捉到这些错误，然后给出详细的错误提示（一般这些信息都需要打印在接口日志文件中，在下文中有一篇文章也写了具体怎么打印日志），这样也方便后续出现问题能快速定位解决。

下面是接口开发常见问题的解决方案 

将结果集转换为json报文格式:https://vip.kingdee.com/link/s/l6xQB

通用GET和POST请求方法:https://vip.kingdee.com/link/s/lp7Bm

http请求报Caused by: java.lang.NoSuchFieldError: INSTANCE怎么处理:https://vip.kingdee.com/link/s/lR6pg

http请求第三方出现乱码的情况怎么处理:https://vip.kingdee.com/link/s/lRdYr

在查询分析器中直接调用接口代码:https://vip.kingdee.com/link/s/lUUqM

报文格式转换可用这个：

结语：

在开发过程中，深刻体会到金蝶 EAS 二次开发既充满挑战又极具价值。对于 webservice 接口的开发，需要仔细规划和精确配置，确保接口的稳定性和高效性。在处理接口日志文件配置时，认识到良好的日志记录对于问题排查和系统优化的重要性。结果集转换为 json 报文格式的过程中，需要对数据结构有清晰的理解，以便准确地进行格式转换。而在运用 GET 和 POST 请求方法以及标准 login\logout 接口时，要严格遵循规范，确保数据的安全传输和系统的正常运行。面对 http 请求报错和乱码处理等常见问题，需要耐心分析和尝试不同的解决方案，积累经验以提高应对问题的能力。总之，金蝶 EAS 二次开发需要不断学习和实践，以提升技术水平。 

后续会持续更新，敬请期待~~~欢迎指正