From 1612bddbf82939ff699bae0e98d71c0dbda60e52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=A2=81=E5=A3=AB=E4=BC=9F?= Date: Sat, 13 Oct 2018 13:25:30 +0800 Subject: [PATCH] Translate the bast-practices/repositories document --- .../Best-Practices/Data-Transfer-Objects.md | 2 +- docs/zh-Hans/Best-Practices/Repositories.md | 52 +++++++++---------- 2 files changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md b/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md index f38dc07084..0a523beb71 100644 --- a/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md +++ b/docs/zh-Hans/Best-Practices/Data-Transfer-Objects.md @@ -1,4 +1,4 @@ -## 数据传输对象最佳实践&约定 +## 数据传输对象最佳实践 & 约定 * **推荐** 在 **application.contracts** 层中定义DTO. * **推荐** 在可能和必要的情况下从预构建的 **基础DTO类** 继承 (如 `EntityDto`, `CreationAuditedEntityDto`, `AuditedEntityDto`, `FullAuditedEntityDto` 等). diff --git a/docs/zh-Hans/Best-Practices/Repositories.md b/docs/zh-Hans/Best-Practices/Repositories.md index c0058df433..26431a633f 100644 --- a/docs/zh-Hans/Best-Practices/Repositories.md +++ b/docs/zh-Hans/Best-Practices/Repositories.md @@ -1,14 +1,14 @@ -## Repository Best Practices & Conventions +## 仓储最佳实践 & 约定 -### Repository Interfaces +### 仓储接口 -* **Do** define repository interfaces in the **domain layer**. -* **Do** define a repository interface (like `IIdentityUserRepository`) and create its corresponding implementations for **each aggregate root**. - * **Do** always use the created repository interface from the application code. - * **Do not** use generic repository interfaces (like `IRepository`) from the application code. - * **Do not** use `IQueryable` features in the application code (domain, application... layers). +* **推荐** 在**领域层**中定义仓储接口. +* **推荐** 为**每个聚合根**定义仓储接口(如 `IIdentityUserRepository`)并创建相应的实现. + * **推荐** 在应用代码中使用仓储时应该注入仓储接口. + * **不推荐** 在应用代码中使用泛型仓储接口(如 `IRepository`). + * **不推荐** 在应用代码(领域, 应用... 层)中使用 `IQueryable` 特性. -For the example aggregate root: +聚合根的示例: ````C# public class IdentityUser : AggregateRoot @@ -17,7 +17,7 @@ public class IdentityUser : AggregateRoot } ```` -Define the repository interface as below: +定义仓储接口, 如下所示: ````C# public interface IIdentityUserRepository : IBasicRepository @@ -26,14 +26,14 @@ public interface IIdentityUserRepository : IBasicRepository } ```` -* **Do not** inherit the repository interface from the `IRepository` interface. Because it inherits the `IQueryable` and the repository should not expose `IQueryable` to the application. -* **Do** inherit the repository interface from `IBasicRepository` (as normally) or a lower-featured interface, like `IReadOnlyRepository` (if it's needed). -* **Do not** define repositories for entities those are **not aggregate roots**. +* **不推荐** 仓储接口继承 `IRepository` 接口. 因为它继承了 `IQueryable` 而仓储不应该将`IQueryable`暴漏给应用. +* **推荐** 通常仓储接口继承自 `IBasicRepository` 或更低级别的接口, 如 `IReadOnlyRepository` (在需要的时候). +* **不推荐** 为实体定义仓储接口,因为它们**不是聚合根**. -### Repository Methods +### 仓储方法 -* **Do** define all repository methods as **asynchronous**. -* **Do** add an **optional** `cancellationToken` parameter to every method of the repository. Example: +* **推荐** 所有的仓储方法定义为 **异步**. +* **推荐** 为仓储的每个方法添加 **可选参数** `cancellationToken` . 例: ````C# Task FindByNormalizedUserNameAsync( @@ -42,7 +42,7 @@ Task FindByNormalizedUserNameAsync( ); ```` -* **Do** create a **synchronous extension** method for each asynchronous repository method. Example: +* **推荐** 为仓储的每个异步方法创建一个 **同步扩展** 方法. 示例: ````C# public static class IdentityUserRepositoryExtensions @@ -58,9 +58,9 @@ public static class IdentityUserRepositoryExtensions } ```` -This will allow synchronous code to use the repository methods easier. +对于同步方法而言, 这会让它们更方便的调用仓储方法. -* **Do** add an optional `bool includeDetails = true` parameter (default value is `true`) for every repository method which returns a **single entity**. Example: +* **推荐** 为仓储中返回**单个实体**的方法添加一个可选参数 `bool includeDetails = true` (默认值为`true`). 示例: ````C# Task FindByNormalizedUserNameAsync( @@ -70,9 +70,9 @@ Task FindByNormalizedUserNameAsync( ); ```` -This parameter will be implemented for ORMs to eager load sub collections of the entity. +该参数由ORM实现, 用来加载实体子集合. -* **Do** add an optional `bool includeDetails = false` parameter (default value is `false`) for every repository method which returns a **list of entities**. Example: +* **推荐** 为仓储中返回**实体列表**的方法添加一个可选参数 `bool includeDetails = false` (默认值为`false`). 示例: ````C# Task> GetListByNormalizedRoleNameAsync( @@ -82,11 +82,11 @@ Task> GetListByNormalizedRoleNameAsync( ); ```` -* **Do not** create composite classes to combine entities to get from repository with a single method call. Examples: *UserWithRoles*, *UserWithTokens*, *UserWithRolesAndTokens*. Instead, properly use `includeDetails` option to add all details of the entity when needed. -* **Avoid** to create projection classes for entities to get less property of an entity from the repository. Example: Avoid to create BasicUserView class to select a few properties needed for the use case needs. Instead, directly use the aggregate root class. However, there may be some exceptions for this rule, where: - * Performance is so critical for the use case and getting the whole aggregate root highly impacts the performance. +* **不推荐** 创建复合类通过调用仓储单个方法返回组合实体. 比如: *UserWithRoles*, *UserWithTokens*, *UserWithRolesAndTokens*. 相反, 正确的使用 `includeDetails` 选项, 在需要时加载实体所有的详细信息. +* **避免** 为了从仓储中获取实体的部分属性而为实体创建投影类. 比如: 避免通过创建BasicUserView来选择所需的一些属性. 相反可以直接使用聚合根类. 不过这条规则有例外情况: + * 性能对于用例来说非常重要,而且使用整个聚合根对性能的影响非常大. -### See Also +### 另外请参阅 -* [Entity Framework Core Integration](Entity-Framework-Core-Integration.md) -* [MongoDB Integration](MongoDB-Integration.md) +* [Entity Framework Core 集成](Entity-Framework-Core-Integration.md) +* [MongoDB 集成](MongoDB-Integration.md)