创建api契约的正确方法

Question

我正在尝试设计一个API。以下是创建合同的两种方法：

方法1：

public class MyController
{
  public void MyAction1(Dictionary<string, dynamic> input)
  {
    //Use input like below
    //Read from input dictionary and apply minimal business logic if needed
    //And Call CustomDataProvider library with input object itself(DataProvider designed in such a way that it takes Dictionary and used values as procedure input. Dictionary key is same as procedure arguments.)
  }

  public void MyAction2(Dictionary<string, dynamic> input)
  {
    //Use input like below
    //Read from input dictionary and apply minimal business logic if needed
    //And Call CustomDataProvider library with input object itself(DataProvider designed in such a way that it takes Dictionary and used values as procedure input. Dictionary key is same as procedure arguments.)
  }
}

在这种情况下，我们根本不需要数据契约。

办法2：

public class MyController
{
    public void MyAction1(MyContractBusinessObject1 input)
    {
        //Do normal business logic processing using input object and call DBProvider by creating a dictionary from business object
    }
    public void MyAction2(MyContractBusinessObject2 input)
    {
        //Do normal business logic processing using input object and call DBProvider by creating a dictionary from business object
    }
}

在这种情况下，我们将有不同的业务类作为契约，用于不同的操作输入。以上哪种方法更好，为什么？

让我举一个例子。假设我的操作正在进行登录和创建新帐户。在第一种情况下，输入将是

new Dictionary<string, dynamic>{
    {"Name","myname"},
    {"Passowrd",'mypassword'} 
}

new Dictionary<string, dynamic>{
    {"Name","myname"},
    {"Passowrd",'mypassword'},
    {"Age",myage},
    {"otherInfo",myotherinfo}
}

但是在方法2中，输入将是

class Login{
    public string Name{get; set;}
    public string Password{get; set;}
}

class NewAccount{
    public string Name{get; set;}
    public string Password{get; set;}
    public int Age{get; set;}
    public OtherInfo OtherInfo{get; set;}
}

Answer 1

我通常对这两种方法都抱怨。如果我不得不在这两种选择之间进行选择，我可能会选择完全类型的选择，因为它将通过查看方法签名和参数类型来告诉我更多关于需要提供什么的信息。字典解决方案要求我查看API文档，更糟糕的是，查看实现的代码，以找出字典中哪些值是有意义的或必需的。问题是，无论您选择哪种方法，您都有某种类型的数据契约。不同之处在于合同有多容易被发现。

如果你提供了一个API，我非常相信让事情变得尽可能简单。如果需要传递给API的内容集对于每个方法来说都很小，那么当所有所需的值都单独传递时(如：controller.Login(myname, mypassword)或controller.NewAccount(myname, mypassword, myage, myotherinfo) )，对API编写代码实际上要容易一些。然后，我就可以从方法签名中看出我应该通过的是什么。如果调用上下文中存在需要猜测的合理值，一些最奇特的IDE甚至会自动填充这些值。我只会将参数绑定到某种类型的结构中，如果这种结构很复杂，或者如果它被用于各种事情的API中。

Answer 2

所以问题是:我应该有一个使用泛型参数的方法，还是使用特定参数的许多方法？

这完全取决于您，但请注意:泛型方法需要通过使用特定的参数类型获得部分免费的验证。还请注意，泛型方法将充当代理，获取泛型类型并将它们转换为特定类型以传递给helper函数(类似于web服务器具有单个例程，该例程接受请求，解析请求，并将其传递给特定于请求页面的例程)。

这完全是主观的，我看到了这两种风格在不同的情况下使用，和两种工作。