推荐的ServiceStack API结构

2 回答

• 134

  首先，“最佳”解决方案是一个相当主观的术语 . 我通常的目标是干燥，可重复使用，高性能的解决方案，促进最小的努力，摩擦和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 项目引用 all 子项目，而最后一个 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 's kept in their own separate implementation and dependency-free dll, you'可以自由地在任何.NET客户端项目中共享此dll - 您可以将其与任何通用C# Service Clients一起使用，以提供没有任何代码生成的端到端类型API .

  ---

  更新

  • 此建议的项目结构现在包含在所有ServiceStackVS' VS.NET Templates中 .

  • Simple Customer REST Example有一个小型的自包含，真实世界的例子，用于使用RDBMS创建简单的REST服务 .

  回复于 2024-05-03T00:16:32+08:00
• 13

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

  Designing a Beautiful REST+JSON API

  回复于 2024-05-03T00:16:32+08:00