RAML用户应遵循的C#与Web API代码生成模式

在过去几年间，REST规范的各种语言正在逐渐流行起来，例如RAML、Swagger以及API Blueprint。但这些语言的主要范畴在于客户端工具，主要用于生成JavaScript或TypeScript文件、模拟对象（mock），以及对应的客户端单元测试。

与此同时，传统的.NET后端开发者往往拥有C#与SQL方面的经验，而对于如何暴露REST服务的各种细节缺乏兴趣。他们更乐于通过在controller的方法中添加一些路由特性（attribute）的方式完成任务，而在数据存储与服务端之间的通信方面发挥他们的核心竞争力。

这种方式通常会造成出现不计其数的信息传达错误，虽然这种错误并不太严重。一旦UI开发者与服务端开发者对于如何暴露某个REST终结点产生了分歧，就必须有人去更新他的代码。通常来说，这种更新只是一个较小的变更，但如果不断重复这一过程，则会造成开发者生产力的极大下降。

为了克服这一问题，UI开发者可以寻求规规范语言的帮助，例如RAML，以生成他们所需的Web API代码。而服务的开发者可专注于如何连接这些代码，而不是为路由特性和HTTP谓词生成各种模拟对象。

本文并不打算讨论如何使用RAML，而是强调RAML，或你所选择的规范语言需要为你生成怎样的代码。

C#代码生成的概念

C# 2.0在设计时就考虑到了代码生成的问题。如今代码生成器的使用已经变得非常普遍，甚至包括Visual Studio本身。代码生成器可创建部分类（partial class）。一个部分类中包括组成整个类所需的部分代码，但未必是全部的代码。这就允许你将类的定义分散在多个文件中，其中部分代码是自动生成的，而另一部分则是手写的。这种分离性能够防止代码生成器删除开发者手写的代码。

不幸的是，这种方式还不完善。部分类允许你添加新的方法，但不能够修改现有方法的行为。因为这一点，我们不得不等待2008年所发布的C# 3，其中引入了部分方法的概念。

从表面上看，部分方法与抽象方法非常相似，但这种比喻是错误的。抽象方法必须在某处实现，否则会使代码无法编译。而部分方法更类似于C++中的空的宏，如果未实现某个部分方法，则编译器会直接取消对该方法的调用，就像这行调用代码从不存在一样。

部分方法的使用有一些严格的需求。由于编译器可能会取消该方法，因此不可返回任何类型，也不可以使用任何“out”参数。不过，你可以在部分方法中使用“ref”参数以返回某个值。由于在使用ref参数时必须在调用该部分方法之前为其赋值，那么即使该部分方法被删除，编译器仍然能够满足明确赋值的规则。

由于以上限制的存在，我们的实现将很大程度上依赖于ref参数。

Controller的模式

所有的REST终结点都必须包含在某个controller类中，以下代码是一个简单的示例：

[GeneratedCode("My Tool", "1.0.0.0")]
[RoutePrefix("api/customer")]
public partial class CustomerController : ApiController
{
    //methods go here
}

以这种方式创建的Web API controller通常包含两种特性，通过中括号表示。GeneratedCode表示这个类是由某个工具生成的，因此开发