对于支持 CRUD 操作的 RESTful API，我应该有一个还是多个复杂类型？答案

【问题标题】：Should I have single or multiple complex types for a RESTful API supporting CRUD operations?对于支持 CRUD 操作的 RESTful API，我应该有一个还是多个复杂类型？
【发布时间】：2012-08-27 10:16:20
【问题描述】：

我有一个支持对实体进行 CRUD 操作的 RESTful API。我应该有一个 xsd 文件来定义所有 CRUD 操作的架构吗？

我问这个问题的原因是，我有一些仅与检索调用相关而不与创建或更新相关的字段。在这种情况下，我应该有一个 xsd 文件并忽略一些用于创建和更新的字段吗？

【问题讨论】：

我想通过询问“多少个 XSD 文件？”你真的在问“有多少单独的元素或复杂类型”。你能解决这个问题吗？文件数量无关紧要，除非我完全错过了这个问题。

标签： web-services rest xsd schema

【解决方案1】：

您的问题似乎将字段使用与 XSD 文件的数量联系在一起，这让我认为您可能缺少一些基本的 XSD 概念。

假设您的问题是，对于给定的实体，您可能检索到更多字段，而不是可以更新；在虚构的Person 实体上进行说明，您可以R（获取）Name、Address、Date of Birth 和 Registered Since 属性，但要C (reate) 实体，您只允许Name、Address 和Date of Birth - 您希望后端系统设置Registered Since 属性。要求是尽可能约束XSD，以提高模型的自描述性。

您可以通过创建 XSD 基本类型来实现这些场景的分离，然后使用另一种类型对其进行扩展，然后该类型将包含您想要的额外字段。您可以在单个文件或两个或多个不同文件中执行此类操作。

<?xml version="1.0" encoding="utf-8" ?>
<!--XML Schema generated by QTAssistant/XML Schema Refactoring (XSR) Module (http://www.paschidev.com)-->
<xsd:schema targetNamespace="http://tempuri.org/XMLSchema.xsd" elementFormDefault="qualified" xmlns="http://tempuri.org/XMLSchema.xsd" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <xsd:complexType name="PersonBase">
        <xsd:sequence>
            <xsd:element name="Name"/>
            <xsd:element name="Address"/>
            <xsd:element name="DateOfBirth"/>
        </xsd:sequence>
    </xsd:complexType>

    <xsd:complexType name="PersonToRetrieve">
        <xsd:complexContent>
            <xsd:extension base="PersonBase">
                <xsd:sequence>
                    <xsd:element name="RegisteredSince"/>
                </xsd:sequence>
            </xsd:extension>
        </xsd:complexContent>
    </xsd:complexType>
</xsd:schema>

注意：上面的 XSD 并非旨在说明 XSD 最佳实践

如果您的环境中不允许扩展/限制，您可以通过xsd:group 实现重用——这不会改变我的观点。所以，我基本上是说你问这个问题的原因 - I have some fields that are relevant only for Retrieve calls and not for Create or Update. - 与 XSD 文件的数量没有任何关系......除非你考虑更多的变量。我会尝试一些我想到的，但我不会提供详尽的清单：

复杂性：如果您要解决的问题很简单，那么请尽量让解决方案保持简单。如上所示，您仍然可以使用一个 XSD 文件解决您的“描述性”问题。如果您将工具视为问题空间的一部分，那么许多工具都存在 XSD 之间复杂关系的问题……有时甚至不支持 xsd:include，命令行变得更加复杂。
XML 命名空间：如果您像我或其他许多人一样愿意将描述您的业务领域的结构与支持您的 API 定义和消息传递的结构分开，那么使用不同的 XML 命名空间是一种常见的做法解决方案。您需要at least 与您决定使用的 XML 命名空间一样多的不同 XSD 文件。这会驱使您拥有多个 XSD 文件。
可重复使用的内容：XSD 内容可以通过多种方式重复使用。如果您希望在许多项目/接口中强制实施一个基本类型系统，那么一个好的做法是将它们编写到一个或多个单独的 XSD 文件中，然后通过其他更具体的 XSD 包含/导入它们。
XML Schema Refactoring：如果您处于人们使用自动重构的环境中，答案将是：谁在乎？我直接知道新手会觉得这个答案自命不凡；然而，在具有复杂系统的现实生活中，由于个人偏好（代码/模型审查等）和/或具有不同支持级别的各种工具/平台，您的问题的某些解决方案实际上很难处理，包括 XSD 到代码，XSD 重构是最有可能让事情顺利运行的唯一方法。

【讨论】：

【解决方案2】：

如果您有不同的字段用于不同的调用，那么是的，您应该使用不同的 XSD 文件，但如果您只根据 CRUD 操作将某些字段留空，那么您不需要创建不同的文件。未使用的字段会在那里，但它们只会留空。

【讨论】：

【解决方案3】：

根据操作，它可能会以下列方式之一处理字段：

必填 - 必须提供且有效。
可选 - 此字段仅在提供且有效时使用。
忽略 - 服务器忽略此字段。例如，对于创建客户操作，ID 和 createdOn 字段不能由客户端设置，被服务器忽略。

对于简单的情况，我将使用单个模式元素来定义实体。我将在文档中解决这些字段的实际用法。

当不同操作对实体的使用存在巨大差异时，单独的实体可能是合适的。例如，管理员的检索客户操作可能会返回比普通用户可用的更多的有关客户的信息。如果这种差异很大，那么定义单独的实体对每个人来说都会更容易。您可以使用架构扩展来扩展基础实体，或者简单地从基础实体中复制并粘贴字段，无论您的环境如何工作。

PS。大多数 Web 服务堆栈，至少在 JAX-RS 和 JAX-WS 中，默认情况下不强制执行模式合规性。最好检查 Web 服务代码中字段的有效性。

【讨论】：