ABP官方文档翻译 5.2 动态We API层

动态Web APID层

• 创建动态Web API控制器
  • ForAll方法
  • 重写ForAll
    • ForMethods
  • Http动词
    • WithVerb方法
    • HTTP特性
    • 命名约定
  • API管理器
  • RemoteServie特性
• 动态Javascript代理
  • AJAX参数
  • 单一服务脚本
  • Anaular集成
• 启用/禁用
• 包装结果
• 关于参数绑定
• FormUrl和FormBody特性
• DTOs对比原始类型

创建动态Web API控制器

　　这个文档是针对ASP.NET Web API的。如果你对ASP.NET Core感兴趣，请参见ASP.NET Core文档。

　　ABP可以为应用层自动生成ASP.NET Web API层。也就是说，如果我们有一个应用服务，如下所示：

public interface ITaskAppService : IApplicationService
{
    GetTasksOutput GetTasks(GetTasksInput input);
    void UpdateTask(UpdateTaskInput input);
    void CreateTask(CreateTaskInput input);
}

　　我们想将这个服务作为一个Web API Controller提供给客户端。ABP可以使用一行配置自动动态的为这个应用服务创建一个Web API Controller：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder.For<ITaskAppService>("tasksystem/task").Build();

　　就这样！一个地址为'/api/services/tasksystem/task'的api controller就创建了，并且所有的方法在客户端都是可用的。这个配置需要在模块的Initialize方法中使用。

　　ITaskAppService是我们想要包装成api controller的应用服务。并不限制为应用服务，但是这是我们约定和推荐的方式。

　　'tasksystem/task'是api controller的名字，名字随意。你应该至少定义一级命名空间，但是你可以定义更深的命名空间如“myCompany/myApplication/myNamespace1/myNamespace2/myServiceName”。'/api/services/'是所有动态web api controller的前缀。所以，api controller的地址将为'/api/services/tasksystem/task'，GetTasks方法地址为'/api/services/tasksystem/task/getTasks'。方法名称转换为camelCase，因为这是在javascript世界的约定。

ForAll方法

　　在应用中，我们会有许多的应用服务，一个一个的创建api controllers是乏味且易忘记的。DynamicApiControllerBuilper提供了一个方法只需调用一次就能为所有应用服务创建web api controllers。示例：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
    .Build();

　　ForAll方法是泛型方法，接收一个接口。第一个参数是包含继承指定接口类的程序集。第二个参数是服务的命名前缀。也就是说在程序集中我们有ITaskAppService和IPersonAppService接口。对于这个配置，服务地址将为'/api/services/tasksystem/task'和'/api/services/tasksystem/person'。计算服务名称：Service和AppService后缀，I前缀移除（对于接口）。服务名称也会转换为camel方式。如果你不喜欢这种约定，使用'WithServiceName'方法可以改变名称。还有一个Where方法用来过滤服务，当你想为除了一部分服务之外的其他所有服务创建时会非常有用。

重写ForAll

　　在ForAll方法之后我们可以重写配置。示例：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
    .Build();

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .For<ITaskAppService>("tasksystem/task")
    .ForMethod("CreateTask").DontCreateAction().Build();

　　在这段代码中，我们动态为程序集中所有的应用服务创建web api controller。然后为一个单独的应用服务（ITaskAppService）重写配置忽略CreateTask方法。

ForMethods

　　当使用ForAll方法时，我们可以使用ForMethods方法更好的调整每一个方法。示例：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .ForAll<IApplicationService>(Assembly.GetExecutingAssembly(), "app")
    .ForMethods(builder =>
    {
        if (builder.Method.IsDefined(typeof(MyIgnoreApiAttribute)))
        {
            builder.DontCreate = true;
        }
    })
    .Build();

　　在这个示例中，使用了一个自定义特性（MyIgnoreApiAttribute）来检查所有的方法，标记了此特性的方法将不会动态创建web api controller action。

Http动词

　　默认，所有的方法以POST的形式创建。所以，为了使用创建的web api actions，客户端应该发送post请求。我们可以使用不同的方式改变这种行为：

WithVerb方法

　　我们可以为方法使用WithVerb，如下：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .For<ITaskAppService>("tasksystem/task")
    .ForMethod("GetTasks").WithVerb(HttpVerb.Get)
    .Build();

HTTP特性

　　我们可以在服务接口方法上添加HttpGet、HttepPost...等特性：

public interface ITaskAppService : IApplicationService
{
    [HttpGet]
    GetTasksOutput GetTasks(GetTasksInput input);

    [HttpPut]
    void UpdateTask(UpdateTaskInput input);

    [HttpPost]
    void CreateTask(CreateTaskInput input);
}

　　为了使用这些特性，我们应该在工程中添加Microsoft.AspNet.WebApi.Core nuget包引用。

命名约定

　　你可以使用WithConventionalVerbs方法取代为每一个方法声明HTTP动词，如下所示：

Configuration.Modules.AbpWebApi().DynamicApiControllerBuilder
    .ForAll<IApplicationService>(Assembly.GetAssembly(typeof(SimpleTaskSystemApplicationModule)), "tasksystem")
    .WithConventionalVerbs()
    .Build();

　　在这种情况下，HTTP动词由方法名前缀决定：

• Get：如果方法名以'Get'开头时使用。
• Put：如果方法名以'Put'或'Update'时使用。
• Delete：如果方法名称以'Delete'或'Remove'开头时使用。
• Post：如果方法名以'Post'，'Create'或'Insert'开头时使用。
• Patch：如果方法名以'Patch'开头时使用。
• 否则，POST为默认的HTTP动词。

　　我们可以为一个特定方法重写它，如之前所描述的那样。　　

API管理器

　　所有的动态web api controllers默认对API管理器是可见的（例如他们都在Swagger中可用）。你可以使用DynamicApiControllerBuilder API或RemoteService特性来控制。

RemoteService特性

　　你可以为任何接口或方法定义使用RemoteService特性来enable/disable(IsEnabled)动态API或API管理器设置(IsMetadataEnabled)。

动态Javascript代理

　　你可以在javascript通过ajax使用动态创建的web api controller。ABP通过为动态web api controllers创建javascript代理来简化了这个操作。所以，你可以在javascript中像一个function一样调用动态web api controller的action。如下所示：

abp.services.tasksystem.task.getTasks({
    state:
}).done(function (result) {
    //use result.tasks here...
});

　　Javascript代理是动态创建的。你应该在页面中包含动态script在使用它之前：

<script src="/api/AbpServiceProxies/GetAll" type="text/javascript"></script>

　　服务方法返回promise(参见jQuery.Deferred)。你可以注册done,fail,then...回调。服务方法内部使用abp.ajax。如果需要，他们处理错误并显示错误信息。

AJAX参数

　　你可能会想传递自定义ajax参数给代理方法。可以作为第二个参数传递，如下所示：

abp.services.tasksystem.task.createTask({
    assignedPersonId: ,
    description: 'a new task description...'
},{ //override jQuery's ajax parameters
    async: false,
    timeout:
}).done(function () {
    abp.notify.success('successfully created a task!');
});

　　这里，jQuery.ajax所有的参数都是有效的。

单一服务脚本

　　'/api/AbpServiceProxies/GetAll'在一个文件里生成所有服务代理。你可以使用'/api/AbpServiceProxies/Get?name=serviceName'并包含在page中生成一个单独的服务代理，如下所示：

<script src="/api/AbpServiceProxies/Get?name=tasksystem/task" type="text/javascript"></script>

Anaular集成

　　ABP可以以angularjs services的方式暴露动态api controllers。考虑下面的示例：

(function() {
    angular.module('app').controller('TaskListController', [
        '$scope', 'abp.services.tasksystem.task',
        function($scope, taskService) {
            var vm = this;
            vm.tasks = [];
            taskService.getTasks({
                state:
            }).success(function(result) {
                vm.tasks = result.tasks;
            });
        }
    ]);
})();

　　我们可以使用服务的名称（和命名空间）注入它。然后，我们可以作为常见的javascript函数调用它的函数。注意，我们注册了success处理方法（而不是done），因为在augular$http服务中也是如此定义的。ABP使用AngularJs的$http服务。如果你想传递$http配置，你可以传递一个配置对象作为服务方法的最后一个参数。

　　为了使用自动生成的服务，你应该在page中包含需要的scripts：

<script src="~/Abp/Framework/scripts/libs/angularjs/abp.ng.js"></script>
<script src="~/api/AbpServiceProxies/GetAll?type=angular"></script>

启用/禁用

　　如果你使用如上定义的ForAll方法，你可以为服务或方法使用RemoteService特性来禁用它。在服务接口中使用，而不是在服务类中。

包装结果

　　ABP使用AjaxResponse对象包装动态web API actions的返回值。参见ajax documentation了解包装的更多信息。你可以enalbe/disable包装每个方法或每个应用服务。参见应用服务的示例：

public interface ITestAppService : IApplicationService
{
    [DontWrapResult]
    DoItOutput DoIt(DoItInput input);
}

　　我们禁用为DoIt方法包装。这个特性应该在接口中声明，不要在实现类中。

　　如果你想更加精确的控制返回结果给客户端时，取消包装会很有用。尤其是，当使用第三方客户端类且它不能处理ABP标注AjaxResponse时会需要。在这种情况下，你应该自己处理异常，因为异常处理将会被禁用（DontWrapResult特性有WrapOnError属性，可以用来启用处理和包装异常）。

　　注意：不论何种情况下，动态javascript代理可以知道结果是否被包装和正确运行。

关于参数绑定

　　ABP在运行时创建Apic Controllers。所以，ABP Web API的model and parameter binding用来绑定模型和参数。你可以阅读它的文档了解更多信息。

FormUrl和FormBody特性

　　FromUri和FromBody特性可以用在应用服务接口来更高级的控制绑定。

DTOs对比原始类型

　　我们强烈建议使用DTOs作为应用服务和web api controllers方法的参数。但是，你可以使用基元类型（如string,int,bool...or nullable 类型如int?,bool?...）作为服务参数。可以使用多个参数，但是只有一个参数允许为复杂类型（因为ASP.NET Web API 的限制）。

返回主目录