一尘不染

推荐的ServiceStack API结构

c#

我正在尝试构造API的最佳方法;我们具有在标准REST结构中设置的评论(列出一个,列出所有,创建,更新等)。这些示例不太适合的地方是:每个评论都可以链接到一个或多个其他类型,例如“事件”,“位置”或“事物”。

我的想法是网址应遵循以下格式:/ event / reviews /(或与此相反的位置,例如/ reviews / event /)/ location /
reviews / / thing / reviews /

但是,我看到的问题是每个对象的“ GET”都应返回父对象,即事件。

那么使用ServiceStack,处理这种情况的最佳方法是什么?是为每个数据请求创建自定义服务,而不是滥用现成的REST设置,还是我错过了更基本的东西?


阅读 482

收藏
2020-05-19

共1个答案

一尘不染

首先,“最佳”解决方案是一个相当主观的术语。我通常将目标放在促进DRY,可重用,高性能的解决方案上,以减少工作量,减少摩擦和聊天,而其他解决方案可能会在遵循REST原理的程度方面定义“最佳”。因此,根据目标是什么,您将获得不同的响应。我只能提供我将如何处理它。

ServiceStack服务实现与其自定义路由脱钩

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

使用逻辑/分层的URL结构

我将使用逻辑Url结构,其目的是代表名词的标识符,该标识符具有分层结构,即,父路径将您的资源分类并为其提供有意义的上下文。因此,在这种情况下,如果您想公开事件并进行评论,则我倾向于以下URL结构:

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

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

实作

对于实现,我通常遵循基于消息的设计,并根据Response类型和调用上下文对所有相关操作进行分组。为此,我将执行以下操作:

[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个 EventsServiceEventReviewsService
类中组织这些消息(取决于代码库的大小)。我应该注意,我对服务请求DTO名称使用了复数形式,以避免与同名的数据模型发生冲突。

虽然我已经分开UpdateEvent,并CreateEvent在这里,我有时会将它们合并成一个单一幂等StoreEvent,如果用例允许操作。

[实物项目结构](https://github.com/ServiceStack/ServiceStack/wiki/Physical-

project-structure)

理想情况下,根级别的 AppHost
项目应保持轻量级且无实现。尽管对于仅提供少量服务的小型项目,将所有内容都放在一个项目中并在需要时根据需要简单地扩展体系结构是可以的。

对于大中型项目,我们建议使用物理结构,在此示例之下,我们假设我们的应用程序称为 EventMan

这些项目的顺序也显示它的依赖,例如顶级EventMan项目引用 的所有 子项目,而最后一个EventMan.ServiceModel项目引用

- 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.ServiceModelDTO保留在各自独立的实现中,并且没有依赖项的dll,您可以按原样在任何.NET客户端项目中自由共享此dll-
您可以将其与任何通用C#服务客户端一起使用以提供最终目的-
端到类型的API,无需任何代码源。


更新资料

2020-05-19