推荐的ServiceStack API结构

Question

我正在尝试找出构建API的最佳方法; 我们在标准REST结构中设置了评论(列表一,列出所有,创建,更新等).在不完全符合示例的情况下:每个评论可以链接到一个或多个其他类型,例如事件,位置或事物.

我的想法是网址将是:/ event/reviews /(或相反的例如/ reviews/event /)/ location/reviews// thing/reviews /

然而,我可以看到的问题是每个这样的"GET"应该返回父对象,即一个事件.

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

Answer 1

首先,"最佳"解决方案是一个相当主观的术语.我通常的目标是干燥,可重复使用,高性能的解决方案,促进最小的努力,摩擦和chattiness,而其他人可能会定义"最佳",它遵循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如果用例允许,我有时会将它们合并为一个幂等操作.

物理项目结构

理想情况下,根级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.

更新

• 此推荐的项目结构现在包含在所有ServiceStackVS的VS.NET模板中.

• 在简单的客户REST示例有创建一个简单的REST服务利用RDBMS的小型自包含的,真实的例子.

Answer 2

不确定它是否有助于你的场景/理解,但我觉得这个演示文稿很有帮助:

设计一个漂亮的REST + JSON API