Webapi作为系统切入点，有太多痛楚。往往典型的符合RestFul规范的系统都会有类似swagger的调测程序。对于星空整体抽象结构而言，也有webapi的表单作为切入向导。那么，要怎么写好一个对接系统，出现的问题能够快速解决。
星空是一个分布式的SOA框架结构，由于是抽象的领域模型设计思想，对外暴露的接口可以利用外观方法，完成操作对接。说白了，星空整体就是一个DynamicForm界面，其他界面都是动态构造的。
那我们拿到需求需要如何下手呢？
一、明确操作定义。
操作定义：在星空里面做简单的增删改查，基本操作可以满足
增：Save，这个时候FID，FEntryId，应当为0；
删：Delete，利用编码或者内码FID、FEntryId来删除；
改：Save，改是基于已经存在的源单进行变更保存，所以FID或者FEntryId必填
查：View/ExecuteBillQuery，基于编码或者过滤条件来查看
提交、审核、反审核、表头业务操作：与保存是一类逻辑操作，利用内码操作。
下推：下推逻辑分为两种，调用PUSH操作，进行整单/整行下推，在下推返回的内码里面更改单据行数据信息，或者自行利用Save操作，创建关联，构建下推关联。
除此之外，我们可以采用反向思路，异构系统中的JSON数据包，不做处理，在星空中写自定义的WebApi接口，系统中可以利用更多的服务操作，甚至可以动态构建View视图，完成复杂的业务逻辑。（后面会讲到）
(Administrator登录，在搜索框中输入 webapi，既可查看单据)
二、根据操作定义写WebApi
既然知道操作了，WebApi通用步骤是登录、传Model数据包。
1. 登录
// 使用webapi引用组件Kingdee.BOS.WebApi.Client.dll
K3CloudApiClient client = new K3CloudApiClient("http://k3cloud/");
var loginResult = client.ValidateLogin("5e60ba7e8d9724","Administrator","888888",2052);
var resultType = JObject.Parse(loginResult)["LoginResultType"].Value<int>();
if (resultType == 1)
{
//TODO 执行操作代码
}2. 执行操作
client.@Operate(@FormId,@data); 这里有两个参数，参数如何写，需要怎么查找，下面提供思路。
@Operate，即操作，第一步确定的操作，具体每个不同操作可以查看图一提示搜索的webapi查看。
@FormId，即表单标识，无论采购订单、销售订单、生产订单，都有元数据对应唯一标识，BOSIDE是我们主要的辅助工具，在BOSIDE中，我们看到整单标识。
或者我们在Webapi测试界面也有唯一标识。
@data，WebApi测试界面中，无论是哪个操作定义，都有对应的data格式，每种操作格式提供的参数大同小异。
以保存为例，2.1~2.9为选用参数，全部为非必录，2.10是我们最主要的参数内容，必录模型包。下面对参数进行基本讲解，未讲解到的就是对应的字面意思，不需要其他解读。
增、改：
2.1，2.2中括号内容针对单据体操作的时候，我们要增加单据体标识确定所在的单据体。以采购订单明细信息的物料编码为例，我们应当写作 FPOOrderEntry.FMaterialId
2.3 如果目标数据大于传入数据行，表示目标数据有多余的行需要删除，其他数据覆盖，仅在编辑数据行的时候使用。
2.8 NumberSearch，我们在传入基础资料保存的时候，例如FMaterialId:{FNumber:”123”}，我们通常是以FNumber去搜索基础资料的，使用FMaterialId的话，会需要先知道对应物料ID。默认开启编码搜索的话，我们所有的基础资料都应该使用FNumber。
删、查、提交、审核、反审核、表头业务操作：
这类操作表头都会有Numbers和Ids 两个参数，这两个是随机选其一的，不需要都填写。选择一个方便且唯一的操作即可。
3. 录单、顺序
WebAPI的工作原理通俗来说，就是模拟录单的过程，根据传入的Json数据包构造的每个字段值，按顺序逐一模拟录单填充（录入）对应字段的值，触发此字段的相关值更新事件、实体服务和插件逻辑。构造完成整个单据的数据包之后，调用Save保存接口（Submit提交、Audit接口），并对应触发保存（提交、审核）的操作校验、操作逻辑、操作单据插件逻辑等整个过程。
模拟录单
在业务员操作录单的时候，我们经常会存在值更新、实体服务规则、代码值更新等影响，导致一个值的变动，其他值也会随着变动。比如，我们在采购订单上录入物料的时候，录入供应商，会根据供应商的价目表等信息，清空已经填写分录行的价格等信息。
顺序
既然录单的顺序已经规定了，那么录入顺序也需要按照系统字段列表属性顺序，从前往后，否则就存在一定的相互覆盖值的情况。
大致就这么多，后续会在附件部分中，贴出可以正常对接系统的JSON数据包示例。
三、自定义的WebApi
熟悉MVC结构的研发应该都清楚，.Net框架的基础结构是通过基础管道中构建HttpApplication和HttpContext，对Http.Sys接收到的请求，进行管道处理。到达HttpModule进行拦截过后，通过路由节点转到正确的Controller进行业务处理。
整个管道过程处理认证、授权等一系列问题，最后在星空的KDsvcHandle的HttpHandle拦截处理业务请求。
那么，星空的自定义webapi利用的也是这个思路，继承KDBaseService，请求路径是xxx.common.kdsvc，到达KDSvcHandle后，通过反射执行我们的操作服务。
按照前面系统预置的webapi示例一样，我们应当先登录，然后在TODO里面执行如何Service示例是Kingdee.K3.SCM.WebApi.ServicesStub.PushSerivce,具体写法是，
这类操作方法，就比较容易发挥想象了，我们也可以通过POST的URL请求来达到目的，这样就可以做一个自定义的前端网页，从CLOUD中抓取服务数据。
总结：
上面的方法，仅仅是用作基本的Webapi书写方法，但实际中还会遇到不同单据不用的业务逻辑影响。
如果在做单结果不与实际表单结果一致的情况下，可以自己在PC端模拟录单，按照webapi的赋值顺序做出来的单是否一致，哪些受影响，即可直观感受！
友情链接
| webapi字段格式 | WebApi返回定制结果 | WebApi 对接的疑难杂症 |
| webapi单据查询接口 | ||
WebApi到底怎么写.docx(845.31KB)
推荐阅读