在Web API中傳遞枚舉參數的最佳實踐

Question

我有一個RESTful Web API項目，我有2個不同的Enum場景，我不確定是最佳實踐。

場景1：直截了當的Enum Param

我的API方法需要一個名為ruleType的參數，其有效值為EmailAddress和IPAddress 。 我在Web API項目中的枚舉如下所示：

public enum RuleType
{
    None = 0,
    EmailAddress = 1,
    IPAddress = 2
}

我對這個場景的問題是，我應該在API的請求中使用?ruleType=EmailAddress （它會自動將該值綁定到API方法中的RuleType屬性）？ 如果是這樣，驗證RuleType參數發送的最佳方式是否是有效的RuleType枚舉值？

場景2：單個參數的多個枚舉值

我的API方法有一個可選fields param，它允許您指定應返回的任何其他數據。 例如&fields=ruleOwner,rule 。 這將在響應中返回那2個額外的數據位。

我在Web API項目中有一個枚舉，它與可能請求的每個可能的field有關，目前，我正在拆分逗號分隔的字段param，然后循環遍歷該枚舉的每個字符串表示，將其解析為等效的枚舉，得到一個Enum值列表，然后我可以在我的API中使用它來檢索相關數據。

這是Enum：

public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    etc.
}

這里最好的做法是什么？ 我正在查看按位枚舉，因此在API請求中發送了一個值，這導致了任何fields組合，但不知道這是否適用於Web API，或者通常是更好的方法來解決這個問題？

Answer 1

最簡單的答案是“沒關系”。

如果controller方法中的參數是枚舉類型

public IHttpActionResult Foo(RuleType ruleType)

在WebAPI中， 它只是工作 - 無論客戶端請求URL是否將?ruleType=1值指定為?ruleType=1或?ruleType=EmailAddress

如果客戶端指定對枚舉無效的值，則拋出異常（ The parameters dictionary contains a null entry for parameter 'ruleType' of non-nullable type 'RuleType' for method 'Foo' ...以及客戶端獲得400 Bad Request響應。

Answer 2

最好的做法是使URI“人類可讀”。 所以我也可以理解為什么你使用Enum作為字符串。 但正如HristoKolev所說，你必須寫一個自定義的Model Binder。

在字段中我認為你不應該使用枚舉的組合。 因為很難理解。 也許你可以創建enum作為枚舉條目的組合

public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    RuleAndRuleOwner = 3,
    etc.
}

Answer 3

對於方案2，使用[Flags]屬性在C＃中為Enums中的位掩碼操作提供了內置支持

[Flags]
public enum OptionalField
{
    None = 0,
    RuleOwner = 1,
    Rule = 2,
    RuleAdministrator = 4,
    RuleEditor = 8,
    ...etc
}

這個SO帖子中描述了這一點

正如Christian在他的回答中已經說過的那樣，在REST API中使用它可能不是一個好習慣，但它應該可行。

Answer 4

是否有多個值，如果您使用Enum作為字符串，則必須手動解析它。 在.NET中，Enums是整數，因此如果要將枚舉發送到默認模型綁定器，則必須執行以下操作： ?ruleType=1 。

你可以編寫自己的模型綁定器來接受字符串，但你必須問問自己為什么要這樣做？ 如果您希望用戶能夠輕松識別網址，請使用字符串。 如果沒有，沒有理由不使用整數。 如您所說，您可以使用FlagsAttribute組合多個值。