c# - 推荐的 ServiceStack API 结构

Question

我正在尝试找出构建 API 的最佳方式；我们有我们在标准 REST 结构中设置的评论(列出一个、列出所有、创建、更新等)。它不太适合示例的地方是:每个评论都可以链接到一种或多种其他类型，例如事件、地点或事物。

我的想法是 url 应该是这样的: /event/reviews/(或反之，例如/reviews/event/) /位置/评论/ /事物/评论/

然而，我可以看到的问题是每个这些的“GET”应该返回父对象，即事件。

那么使用 ServiceStack，处理这种情况的最佳方式是什么？是为每个数据请求创建自定义服务而不是滥用开箱即用的 REST 设置，还是我错过了一些更基本的东西？

Answer 1

首先，“最佳”解决方案是一个相当主观的术语。我通常会以 DRY、可重用、高性能解决方案为目标，以促进最少的努力、摩擦和闲聊，而其他人可能会根据它与 REST 原则的紧密程度来定义“最佳”。所以你会根据目标是什么得到不同的回应。我只能提供我将如何处理它。

ServiceStack 服务实现与其自定义路由分离

要记住的一件事是，您在 ServiceStack 中定义和设计服务的方式与公开它们的方式相当分离，因为您可以在任何自定义路由下公开您的服务。 ServiceStack 鼓励基于消息的设计，因此您应该为每个操作提供不同的消息。

使用逻辑/分层的 Url 结构

我会使用一个逻辑 Url 结构，我的目标是表示一个名词的标识符，它是分层结构的，即父路径对您的资源进行分类并为其提供有意义的上下文。因此，在这种情况下，如果您想公开事件和评论，我倾向于使用以下 url 结构:

/events             //all events
/events/1           //event #1
/events/1/reviews   //event #1 reviews

这些资源标识符中的每一个都可以应用任何 HTTP 动词

实现

对于实现，我通常遵循基于消息的设计，并根据响应类型和调用上下文对所有相关操作进行分组。为此，我会做类似的事情:

[Route("/events", "GET")]
[Route("/events/category/{Category}", "GET")] //*Optional top-level views
public class SearchEvents : IReturn<SearchEventsResponse>
{
   //Optional resultset filters, e.g. ?Category=Tech&Query=servicestack
   public string Category { get; set; } 
   public string Query { get; set; }
}

[Route("/events", "POST")]
public class CreateEvent : IReturn<Event>
{
   public string Name { get; set; }
   public DateTime StartDate { get; set; }
}

[Route("/events/{Id}", "GET")]
[Route("/events/code/{EventCode}", "GET")] //*Optional
public class GetEvent : IReturn<Event>
{
   public int Id { get; set; }
   public string EventCode { get; set; } //Alternative way to fetch an Event
}

[Route("/events/{Id}", "PUT")]
public class UpdateEvent : IReturn<Event>
{
   public int Id { get; set; }
   public string Name { get; set; }
   public DateTime StartDate { get; set; }
}

并遵循类似的事件评论模式

[Route("/events/{EventId}/reviews", "GET")]
public class GetEventReviews : IReturn<GetEventReviewsResponse>
{
   public int EventId { get; set; }
}

[Route("/events/{EventId}/reviews/{Id}", "GET")]
public class GetEventReview : IReturn<EventReview>
{
   public int EventId { get; set; }
   public int Id { get; set; }
}

[Route("/events/{EventId}/reviews", "POST")]
public class CreateEventReview : IReturn<EventReview>
{
   public int EventId { get; set; }
   public string Comments { get; set; }
}

基于这些消息，实现应该相当直接，我将在 2 个 EventsService 和 EventReviewsService 类中组织这些消息(取决于代码库大小)。我应该注意，我自己对服务请求 DTO 名称使用复数形式，以避免与同名的数据模型发生冲突。

尽管我在这里将 UpdateEvent 和 CreateEvent 分开，但有时我会将它们合并为一个幂等的 StoreEvent 操作，如果使用-情况允许。

Physical Project Structure

理想情况下，根级 AppHost 项目应保持轻量级且无需实现。尽管对于只有少数服务的小型项目来说，将所有内容都放在一个项目中并在需要时简单地扩展您的架构是可以的。

对于大中型项目，我们推荐以下物理结构，为了本示例的目的，我们假设我们的应用程序名为 EventMan。

项目的顺序也显示了它的依赖关系，例如顶级 EventMan 项目引用所有 子项目，而最后一个 EventMan.ServiceModel 项目引用none:

- EventMan
    AppHost.cs              // ServiceStack ASP.NET Web or Console Host Project

- EventMan.ServiceInterface // Service implementations (akin to MVC Controllers)
    EventsService.cs
    EventsReviewsService.cs

- EventMan.Logic            //For larger projs: pure C# logic, data models, etc
    IGoogleCalendarGateway  //E.g of a external dependency this project could use

- EventMan.ServiceModel     //Service Request/Response DTOs and DTO types
    Events.cs               //SearchEvents, CreateEvent, GetEvent DTOs 
    EventReviews.cs         //GetEventReviews, CreateEventReview
    Types/
      Event.cs              //Event type
      EventReview.cs        //EventReview type

有了 EventMan.ServiceModel DTO 保存在它们自己单独的实现和无依赖的 dll 中，您可以在任何 .NET 客户端项目中按原样自由共享此 dll - 您可以与任何通用 C# Service Clients 一起使用提供无需任何代码生成的端到端类型化 API。

---

更新

• 这个推荐的项目结构现在包含在所有 ServiceStackVS' VS.NET Templates 中.

• Simple Customer REST Example有一个使用 RDBMS 创建简单 REST 服务的独立的真实世界小示例。