REST API 和 DDD

Question

在我的项目中使用 DDD 方法。

该项目有聚合（实体）交易。这个聚合有很多用例。

对于这个聚合，我需要创建一个 rest api。

用标准：创建和删除没问题。

1) CreateDealUseCase（名称、价格和许多其他参数）；

POST /rest/{version}/deals/
{ 
   'name': 'deal123',
   'price': 1234;
   'etc': 'etc'
}

2) DeleteDealUseCase(id)

DELETE /rest/{version}/deals/{id}

但是如何处理其余的用例呢？

• HoldDealUseCase(id, reason);
• UnholdDealUseCase(id);
• CompleteDealUseCase（id 和许多其他参数）；
• CancelDealUseCase(id, amercement, reason);
• ChangePriceUseCase(id, newPrice, reason);
• ChangeCompletionDateUseCase(id, newDate, amercement, whyChanged);
• 等（共20个用例）...

有什么解决办法？

1) 使用动词：

PUT /rest/{version}/deals/{id}/hold
{ 
   'reason': 'test'
}

但是！ url中不能使用动词（在REST理论中）。

2) 使用完成状态（将在用例之后）：

PUT /rest/{version}/deals/{id}/holded
{ 
   'reason': 'test'
}

就我个人而言，它看起来很丑。也许我错了？

3) 对所有操作使用 1 个 PUT 请求：

PUT /rest/{version}/deals/{id}
{ 
   'action': 'HoldDeal',
   'params': {'reason': 'test'}
}

PUT /rest/{version}/deals/{id}
{ 
   'action': 'UnholdDeal',
   'params': {}
}

很难在后端处理。 此外，很难记录。由于 1 个操作有许多不同的请求变体，这些变体已经依赖于特定的响应。

所有解决方案都有明显的缺点。

我在互联网上阅读了很多关于 REST 的文章。到处都是理论，我的具体问题怎么来这里？

Answer 1

独立于领域层设计你的 rest api。

领域驱动设计的一个关键概念是不同软件层之间的低耦合。所以，当你设计你的 rest api 时，你会考虑你可以拥有的最好的 rest api。然后，应用层的角色就是调用领域对象来执行所需的用例。

我无法为你设计你的 rest api，因为我不知道你想做什么，但这里有一些想法。

据我了解，您拥有交易资源。正如你所说，创建/删除很容易：

• POST /rest/{version}/deals
• 删除 /rest/{version}/deals/{id}。

然后，您想“持有”一笔交易。我不知道这意味着什么，您必须考虑它在资源“交易”中的变化。它会改变一个属性吗？如果是，那么您只是在修改 Deal 资源。

PUT /rest/{version}/deals/{id}

{
    ...
    held: true,
    holdReason: "something",
    ...
}

它增加了什么吗？您可以对交易进行多次保留吗？在我看来，“持有”是一个名词。如果它很难看，就找一个更好的名词。

POST /rest/{version}/deals/{id}/holds

{
    reason: "something"
}

另一个解决方案：忘记 REST 理论。如果您认为在 url 中使用动词会使您的 api 更清晰、更高效、更简单，那么请务必这样做。你或许可以找到一种方法来避免它，但如果你做不到，就不要因为这是常态而做出丑陋的事情。

看看twitter's api：很多开发人员说twitter 有一个设计良好的API。 Tadaa，它使用动词！谁在乎，只要它既酷又好用？

我无法为你设计你的 api，你是唯一知道你的用例的人，但我再说一遍我的两个建议：

• 自己设计rest api，然后使用应用层按正确的顺序调用相应的领域对象。这正是应用层的用途。
• 不要盲目地遵循规范和理论。是的，您应该尽可能地遵循良好的做法和规范，但如果不能，则将它们抛在脑后（当然要经过仔细考虑）

Answer 2

我在互联网上阅读了很多关于 REST 的文章。

根据我在这里看到的，您确实需要至少观看一次 Jim Webber 关于 REST 和 DDD 的演讲

• Rest in Practice
• Domain Driven Design for RESTful Systems

但是如何处理其余的用例呢？

暂时忽略 API - 您将如何处理 HTML 表单？

您可能有一个网页，其中显示了Deal 的表示，上面有一堆链接。一个链接会将您带到HoldDeal 表单，另一个链接会将您带到ChangePrice 表单，依此类推。这些表单中的每一个都需要填写零个或多个字段，并且每个表单都会发布到某个资源以更新域模型。

他们都会发布到同一个资源吗？也许，也许不是。它们都将具有相同的媒体类型，因此如果它们都发布到同一个 Web 端点，您将不得不解码另一端的内容。

鉴于这种方法，您如何实施您的系统？好吧，根据您的示例，媒体类型希望为 json，但其余部分确实没有任何问题。

1) 使用动词：

没关系。

但是！ url中不能使用动词（在REST理论中）。

嗯……不。 REST 不关心资源标识符的拼写。有一堆 URI 最佳实践声称动词是不好的——这是真的——但这不是 REST 遵循的。

但是如果人们这么挑剔，你可以为命令命名端点而不是动词。 （即：“hold”不是动词，它是一个用例）。

对所有操作使用 1 个 PUT 请求：

老实说，那个也不错。虽然您不想共享 URI（因为 PUT 方法的指定方式），但使用客户端可以指定唯一标识符的模板。

重点是：您正在基于 HTTP 和 HTTP 方法构建 API。 HTTP 专为文档传输而设计。客户端给你一个文档，描述你的域模型中请求的更改，你将更改应用到域（或不应用），并返回另一个描述新状态的文档。

暂时借用 CQRS 词汇，您正在发布命令以更新您的域模型。

PUT /commands/{commandId}
{ 
   'deal' : dealId
   'action': 'HoldDeal',
   'params': {'reason': 'test'}
}

理由 - 您正在将特定命令（具有特定 Id 的命令）放入命令队列，这是一个集合。

PUT /rest/{version}/deals/{dealId}/commands/{commandId}
{ 
   'action': 'HoldDeal',
   'params': {'reason': 'test'}
}

是的，那也很好。

再看看 RESTBucks。这是一个咖啡店协议，但所有的 api 只是传递小文件来推进状态机。

Answer 3

我将用例 (UC) 分为 2 组：命令和查询 (CQRS)，并且我有 2 个 REST 控制器（一个用于命令，另一个用于查询）。由于 POST/GET/PUT/DELETE 的结果，REST 资源不必是模型对象即可对其执行 CRUD 操作。资源可以是您想要的任何对象。实际上，在 DDD 中，您不应该将域模型暴露给控制器。

(1) RestApiCommandController： 每个命令用例一个方法。 URI 中的 REST 资源是命令类名称。该方法始终是 POST，因为您创建命令，然后通过命令总线（在我的情况下为中介）执行它。请求正文是映射命令属性（UC 的 args）的 JSON 对象。

例如：http://localhost:8181/command/asignTaskCommand/

@RestController
@RequestMapping("/command")
public class RestApiCommandController {

private final Mediator mediator;    

@Autowired
public RestApiCommandController (Mediator mediator) {
    this.mediator = mediator;
}    

@RequestMapping(value = "/asignTaskCommand/", method = RequestMethod.POST)
public ResponseEntity<?> asignTask ( @RequestBody AsignTaskCommand asignTaskCommand ) {     
    this.mediator.execute ( asigTaskCommand );
    return new ResponseEntity ( HttpStatus.OK );
}

---

(2) RestApiQueryController： 每个查询用例一个方法。这里 URI 中的 REST 资源是查询返回的 DTO 对象（作为集合的元素，或仅作为一个元素）。方法始终是 GET，查询 UC 的参数是 URI 中的参数。

例如：http://localhost:8181/query/asignedTask/1

@RestController
@RequestMapping("/query")
public class RestApiQueryController {

private final Mediator mediator;    

@Autowired
public RestApiQueryController (Mediator mediator) {
    this.mediator = mediator;
}    

@RequestMapping(value = "/asignedTask/{employeeId}", method = RequestMethod.GET)
public ResponseEntity<List<AsignedTask>> asignedTasksToEmployee ( @PathVariable("employeeId") String employeeId ) {

    AsignedTasksQuery asignedTasksQuery = new AsignedTasksQuery ( employeeId);
    List<AsignedTask> result = mediator.executeQuery ( asignedTasksQuery );
    if ( result==null || result.isEmpty() ) {
        return new ResponseEntity ( HttpStatus.NOT_FOUND );
    }
    return new ResponseEntity<List<AsignedTask>>(result, HttpStatus.OK);
} 

注意： Mediator 属于 DDD 应用层。它是 UC 边界，它查找命令/查询，并执行相应的应用程序服务。

Answer 4

文章Exposing CQRS Through a RESTful API 是解决您的问题的详细方法。您可以查看prototype API。几个cmets：

• 这是一种复杂的方法，因此您可能不需要实现文章中的所有内容：通过 HTTP 的 ETag 和 If-Match 的事件溯源并发是一种“高级”功能
• 这是一种自以为是的方法：DDD 命令类型是通过媒体类型标头发送的，而不是通过正文发送的。就我个人而言，我觉得这很有趣……但不确定是否会以这种方式实现