二开案例.WebApi.从零开发自定义WebApi接口

栏目：云星空知识作者：金蝶来源：金蝶云社区发布：2024-09-23浏览：1

【应用场景】

开发自定义WebApi接口，实现个性化需求。

【案例演示】

添加自定义WebApi接口，实现定义接口、调用接口、传入参数、访问数据库、返回数据等功能。

【实现步骤】

<1>添加自定义WebApi接口类，代码如下。

using Kingdee.BOS.App.Data;
using Kingdee.BOS.ServiceFacade.KDServiceFx;
using Kingdee.BOS.WebApi.ServicesStub;
using System;
namespace Jac.XkDemo.BOS.WebApi
{
    /// <summary>
    /// 【WebApi】自定义WebApi接口
    /// </summary>
    public class CustomWebApiDemoWebApiService : AbstractWebApiBusinessService
    {
        public CustomWebApiDemoWebApiService(KDServiceContext context)
            : base(context)
        {
            //
        }
        /// <summary>
        /// 测试接口
        /// 不需要使用上下文，不需要访问数据中心，则不需要客户端登录
        /// </summary>
        /// <param name="arg1">参数1</param>
        /// <param name="arg2">参数2</param>
        /// <returns>返回请求方法和请求参数</returns>
        public object DoSth(string arg1, int arg2)
        {
            var responseDto = new
            {
                ApiName = System.Reflection.MethodInfo.GetCurrentMethod().Name,
                Args = new object[] { arg1, arg2 }
            };
            return responseDto;
        }
        /// <summary>
        /// 测试接口2
        /// 需要使用上下文，需要访问数据中心，则需要客户端登录
        /// </summary>
        /// <param name="arg1">参数1</param>
        /// <param name="arg2">参数2</param>
        /// <returns>返回登录用户名和请求方法和请求参数</returns>
        public object DoSth2(string arg1, int arg2)
        {
            var ctx = KDContext.Session.AppContext;
            if (ctx == null)
            {
                // 会话超时，需重新登录
                throw new Exception("ctx = null");
            }
            // 访问数据库获取用户名
            var sql = "SELECT FNAME FROM T_SEC_USER WHERE FUSERID=@FUSERID";
            var paramUserId = new Kingdee.BOS.SqlParam("@FUSERID", Kingdee.BOS.KDDbType.Int32, ctx.UserId);
            var userName = DBUtils.ExecuteScalar(ctx, sql, string.Empty, paramUserId);
            var responseDto = new
            {
                UserName = userName,
                ApiName = System.Reflection.MethodInfo.GetCurrentMethod().Name,
                Args = new object[] { arg1, arg2 }
            };
            return responseDto;
        }
    }
}

<2>拷贝WebApi接口组件到应用站点的WebSite\Bin目录下，重启IIS，开发完毕。

<3>添加自定义WebApi接口的单元测试代码，可通过单元测试代码，测试接口的运行情况。

using Kingdee.BOS.WebApi.Client;
using Microsoft.VisualStudio.TestTools.UnitTesting;
using Newtonsoft.Json;
using System;
namespace Jac.XkDemo.BOS.WebApiTests
{
    /// <summary>
    /// 【WebApi】CustomWebApiDemo
    /// </summary>
    [TestClass]
    public class CustomWebApiDemoWebApiServiceTests
    {
        [TestMethod]
        public void DoSthTest()
        {
            #region Init
            // 星空站点Url
            var webSite = "http://localhost:1700/k3cloud/";
            #endregion
            #region Action
            var client = new K3CloudApiClient(webSite);
            var rval = client.Execute<Kingdee.BOS.JSON.JSONObject>("Jac.XkDemo.BOS.WebApi.CustomWebApiDemoWebApiService.DoSth,Jac.XkDemo.BOS.WebApi", new object[] { "abc", 123 });
            #endregion
            #region Assert
            Assert.IsTrue(rval != null);
            Console.WriteLine(JsonConvert.SerializeObject(rval));
            #endregion
        }
        [TestMethod]
        public void DoSth2Test()
        {
            #region Init
            // 星空站点Url
            var webSite = "http://localhost:1700/k3cloud/";
            // 数据中心ID(账套ID)
            var dbId = "6371de6bdb991c";
            // 登录账号          
            var userName = "demo";
            //第三方系统应用Id             
            var password = "888888";
            // 登录语言
            var lcId = 2052;
            #endregion
            #region Action
            // 登录
            var client = new K3CloudApiClient(webSite);
            var loginResult = client.Login(dbId, userName, password, lcId);
            if (!loginResult)
            {
                Assert.IsFalse(true);
                return;
            }
            var rval = client.Execute<Kingdee.BOS.JSON.JSONObject>("Jac.XkDemo.BOS.WebApi.CustomWebApiDemoWebApiService.DoSth2,Jac.XkDemo.BOS.WebApi", new object[] { "abc", 123 });
            #endregion
            #region Assert
            Assert.IsTrue(rval != null);
            Console.WriteLine(JsonConvert.SerializeObject(rval));
            #endregion
        }
    }
}

【功能验证】

下面使用Postman对接口进行测试验证。

<1>DoSth接口

不需要登录，直接调用接口。

请求Url：http://localhost:1700/k3cloud/Jac.XkDemo.BOS.WebApi.CustomWebApiDemoWebApiService.DoSth,Jac.XkDemo.BOS.WebApi.common.kdsvc

请求数据包：

{
"parameters": ["abc",
123]
}

返回数据包：

{
"ApiName": "DoSth",
"Args": ["abc",
123]
}

<2>DoSth2接口

先登录，再调用接口。

登录接口：

请求Url：http://localhost:1700/K3Cloud/Kingdee.BOS.WebApi.ServicesStub.AuthService.ValidateUser.common.kdsvc

请求数据包：

{
"parameters": ["6371de6bdb991c",
"demo",
"888888",
2052]
}

返回数据包：

调用接口。

请求Url：http://localhost:1700/k3cloud/Jac.XkDemo.BOS.WebApi.CustomWebApiDemoWebApiService.DoSth2,Jac.XkDemo.BOS.WebApi.common.kdsvc

请求数据包：

{
"parameters": ["abc",
123]
}

返回数据包：

{
"UserName": "demo",
"ApiName": "DoSth2",
"Args": ["abc",
123]
}

---------------------------------------------------------------------------------------------------------

【知识点】

<1>WebApi接口必须继承自

Kingdee.BOS.WebApi.ServicesStub.AbstractWebApiBusinessService

<2>客户端调用自定义WebApi接口时，需传递自定义接口的类全名和程序集名。

下面以本文中的自定义接口为例说明：

Jac.XkDemo.BOS.WebApi.CustomWebApiDemoWebApiService.DoSth2,Jac.XkDemo.BOS.WebApi

逗号前面部分为自定义接口类全名（命名空间+类名+方法名）

逗号后面部分为自定义接口类所在项目的编译后的组件（程序集）的名称。

【注意】

自定义接口的命名空间必须包含独立的子命名空间WebApi！

否则可能会造成安全校验失败，请求被拦截，报403错误。

<3>WebApi存在登录超时机制，当登录成功后，会给当前用户在服务端创建会话和上下文，当会话超时后，上下文会被回收变成null，建议在接口方法中加上Context不等于null的判断，及时阻断会话超时的请求，避免接口在上下文丢失的情况下继续执行从而产生一些奇怪的异常，例如：

public object DoSth(string arg1)
{
    if (this.KDContext.Session.AppContext == null)
    {
        // 会话超时，需重新登录
        throw new Exception("ctx=null");
    }
    // TODO
}

<4>数据中心内码抓取方式：

方式1：