从 JavaScript 代码中调用你的 HTTP API 是很典型的。为此，通常需要处理低级别的 AJAX 调用，如 $.ajax 或更好的 abp.ajax。ABP 框架为从 JavaScript 代码调用 HTTP API 提供了更好的方式：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 更改为你的应用程序的根 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') //Get id from somewhere!
    .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') //Get id from somewhere!
    .then(function () {
        abp.notify.info('Successfully deleted!');
    });

禁用动态 JavaScript 代理

当你创建应用程序或模块时，默认使用动态客户端代理生成方法。如果要为应用程序使用静态生成的客户端代理，应在模块类的 ConfigureServices 方法中为应用程序或模块显式禁用它，如下例所示：

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

app 代表了这个示例中的主应用程序，如果你正在创建一个应用程序，它就可以工作。如果你正在开发一个应用程序模块，那么就使用你的模块名称。

AJAX 详情

JavaScript 客户端代理函数在底层使用 abp.ajax。因此，你拥有与自动错误处理相同的好处。此外，你可以通过提供选项来完全控制 AJAX 调用。

返回值

每个函数都返回一个 Deferred 对象。这意味着你可以通过 then 链接来获取结果，catch 来处理错误，always 来在操作完成后（成功或失败）执行一个动作。

AJAX 选项

在你自己的参数之后，每个函数都会得到一个额外的最后一个参数。最后一个参数被称为 ajaxParams。它是一个覆盖 AJAX 选项的对象。

示例：设置 type 和数据类型 AJAX 选项

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

可查看 jQuery.ajax 文档以获取所有可用选项。