静态 JavaScript API 客户端代理

通常我们需要通过JavaScript代码调用HTTP API。常规做法是使用底层AJAX调用，例如$.ajax或更优选的abp.ajax。ABP框架提供了一种更高效的JavaScript调用方式：JavaScript API客户端代理！

静态与动态 JavaScript 客户端代理对比

ABP提供两种类型的客户端代理生成系统。本文重点介绍静态客户端代理，该方式在开发阶段生成客户端代码。您也可以查阅动态JavaScript API客户端代理文档了解运行时生成代理的使用方法。

开发阶段（静态）客户端代理具有轻微的性能优势，因其无需在运行时获取HTTP API定义。但需要注意，当您修改API端点定义后，必须重新生成客户端代理代码。而动态客户端代理在运行时生成，能提供更便捷的开发体验。

快速入门示例

应用服务定义

假设您已定义如下应用服务接口：

using System;
using System.Threading.Tasks;
using Volo.Abp.Application.Dtos;
using Volo.Abp.Application.Services;

namespace Acme.BookStore.Authors
{
    public interface IAuthorAppService : IApplicationService
    {
        Task<AuthorDto> GetAsync(Guid id);

        Task<PagedResultDto<AuthorDto>> GetListAsync(GetAuthorListDto input);

        Task<AuthorDto> CreateAsync(CreateAuthorDto input);

        Task UpdateAsync(Guid id, UpdateAuthorDto input);

        Task DeleteAsync(Guid id);
    }
}

您可以通过Web应用开发教程系统学习如何创建应用服务、将其发布为HTTP API并通过JavaScript代码调用的完整流程。

生成JavaScript代码

生成客户端代理代码时需确保服务端处于运行状态。请先启动承载HTTP API的应用程序（根据解决方案结构可能是Web应用或HttpApi.Host应用）。

在Web项目根目录（.csproj文件所在路径）打开命令行终端，执行以下命令：

abp generate-proxy -t js -u https://localhost:53929/

如果尚未安装，请先安装ABP CLI。请将示例URL替换为您的应用程序根地址。

该命令将在ClientProxies目录下生成以下文件：

本示例中生成的代理文件为app-proxy.js。文件中包含的典型代理函数示例如下：

acme.bookStore.authors.author.get = function(id, ajaxParams) {
  return abp.ajax($.extend(true, {
    url: abp.appPath + 'api/app/author/' + id + '',
    type: 'GET'
  }, ajaxParams));
};

generate-proxy命令仅为您应用程序中定义的API生成代理（默认模块名为app）。若开发模块化应用，可通过-m（或--module）参数指定目标模块。其他选项请参考ABP CLI文档中的generate-proxy章节。

使用代理函数

使用代理函数前，需先在页面中引入app-proxy.js文件：

<abp-script src="/client-proxies/app-proxy.js"/>

本例使用了abp-script标签助手。虽然也可使用标准script标签，但推荐采用abp-script方式引入JavaScript文件。

现在您可以从JavaScript代码中直接调用应用服务方法，就像调用普通JavaScript函数一样。这些JavaScript函数与C#方法具有完全相同的函数名、参数和返回值。

示例：获取单个作者信息

acme.bookStore.authors.author
    .get("7245a066-5457-4941-8aa7-3004778775f0") //从某处获取ID！
    .then(function(result){
      console.log(result);
    });

示例：获取作者列表

acme.bookStore.authors.author.getList({
  maxResultCount: 10
}).then(function(result){
  console.log(result.items);
});

示例：删除作者

acme.bookStore.authors.author
    .delete('7245a066-5457-4941-8aa7-3004778775f0') //从某处获取ID！
    .then(function() {
        abp.notify.info('删除成功！');
    });

禁用动态 JavaScript 代理

创建应用或模块时，系统默认采用动态客户端代理生成方案。如需改用静态生成方案，请在模块类的ConfigureServices方法中显式禁用，示例如下：

Configure<DynamicJavaScriptProxyOptions>(options =>
{
    options.DisableModule("app");
});

此处的app代表主应用程序（适用于应用开发场景）。若开发应用模块，请使用您的模块名称。

AJAX技术细节

JavaScript客户端代理函数底层使用abp.ajax，因此您可享受自动错误处理等优势。同时通过配置参数可完全控制AJAX调用。

返回值特性

每个函数均返回延迟对象。这意味着您可以通过then获取结果，通过catch处理错误，通过always在操作完成（无论成功失败）后执行指定操作。

AJAX参数配置

所有函数在自身参数后接收一个额外参数，该参数名为ajaxParams。这是一个用于重写AJAX配置选项的对象。

示例：设置type和dataTypeAJAX选项

acme.bookStore.authors.author
    .delete('7245a066-5457-4941-8aa7-3004778775f0', {
        type: 'POST',
        dataType: 'xml'
    })
    .then(function() {
        abp.notify.info('删除成功！');
    });

完整配置选项请参阅jQuery.ajax文档。