建议的ServiceStack API结构

Question

建议的ServiceStack API结构

c#apiservicestack

67

我在努力找到最佳的API结构方式; 我们已经使用标准REST结构设置了评论（列出一个、列出所有、创建、更新等）。其中不太符合示例的地方是：每个评论可以链接到一个或多个其他类型，例如事件、位置或物品。

我的想法是URL应该是这样的： /event/reviews/ （或者反过来，例如 /reviews/event/） /location/reviews/ /thing/reviews/

然而，我发现问题在于每个请求的 "GET" 应该返回父对象，即事件。

因此，在使用 ServiceStack 时，处理这种情况的最佳方法是什么？是为每个数据请求创建自定义服务，而不是滥用开箱即用的REST设置，还是我错过了更基本的内容？

- Tim

1个回答

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- mythz · Accepted Answer

首先，“最佳”解决方案是一个相当主观的术语。我通常会针对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; }
}

根据这些信息，实现应该相当简单。我将在两个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.ServiceModel DTO保留在其自己的独立实现和无依赖的dll中，您可以自由地在任何.NET客户端项目中原样共享此dll - 您可以使用任何通用的C＃服务客户端与之配合，提供端到端的类型化API，而无需任何代码生成。

更新

现在所有ServiceStackVS的VS.NET模板都包含了这个推荐的项目结构。
简单客户端REST示例是一个小型自包含的真实世界示例，演示如何创建一个简单的REST服务并利用关系型数据库。