Skip to content

Commit b2d478c

Browse files
hhkohhko
committed
docs(release): v1.0.0-alpha.3 릴리스 노트 추가 (EN/KR)
1 parent 3cbfacc commit b2d478c

2 files changed

Lines changed: 710 additions & 0 deletions

File tree

‎.release-notes/v1/v1.0.0-alpha.3/RELEASE-v1.0.0-alpha.3-KR.md‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
1+
---
2+
title: Functorium v1.0.0-alpha.3 릴리스 노트
3+
description: Functorium v1.0.0-alpha.3은 IRepository 재설계와 Specification 기반 연산, EF Core 대량 처리 성능 개선을 포함합니다.
4+
date: 2026-04-11
5+
---
6+
7+
# Functorium 릴리스 v1.0.0-alpha.3
8+
9+
## 개요
10+
11+
Functorium v1.0.0-alpha.3은 **IRepository 재설계**와 **EF Core 성능 최적화**에 집중합니다. Repository 인터페이스가 Write Single, Write Batch, Read, Specification 4개 책임 그룹으로 재구성되었으며, 배치 연산은 Change Tracker를 우회하여 처리량이 크게 향상됩니다. 새로운 `[GenerateSetters]` Source Generator는 EF Core `ExecuteUpdateAsync` 도입에 필요한 보일러플레이트를 제거합니다.
12+
13+
**주요 기능**:
14+
15+
- **IRepository 재설계**: Write Single / Write Batch / Read / Specification 4그룹 분리, Specification 기반 `Exists`, `Count`, `DeleteBy` 연산 추가
16+
- **EF Core 성능 최적화**: `Update`/`UpdateRange`가 `ExecuteUpdateAsync`로 Change Tracker 우회, `CreateRange`가 대량 데이터 청크 삽입 지원
17+
- **[GenerateSetters] Source Generator**: EF Core 모델의 `ApplySetters` 자동 생성, 수동 `SetProperty` 보일러플레이트 제거
18+
19+
## Breaking Changes
20+
21+
### 1. CreateRange/UpdateRange 반환 타입 변경
22+
23+
배치 쓰기 연산이 Aggregate 컬렉션(`Seq<TAggregate>`) 대신 영향 받은 행 수(`int`)를 반환합니다. 배치 호출자가 이미 Aggregate 참조를 보유하고 있으므로 성공/건수 신호만 필요하다는 원칙에 따릅니다.
24+
25+
**이전 (v1.0.0-alpha.2)**:
26+
```csharp
27+
// 배치 연산이 Aggregate 컬렉션을 반환
28+
FinT<IO, Seq<TAggregate>> CreateRange(IReadOnlyList<TAggregate> aggregates);
29+
FinT<IO, Seq<TAggregate>> UpdateRange(IReadOnlyList<TAggregate> aggregates);
30+
31+
// 호출자 사용 방식
32+
var created = await repository.CreateRange(orders).RunAsync();
33+
Seq<Order> orders = created.ThrowIfFail(); // Seq<Order>
34+
```
35+
36+
**이후 (v1.0.0-alpha.3)**:
37+
```csharp
38+
// 배치 연산이 영향 받은 건수를 반환
39+
FinT<IO, int> CreateRange(IReadOnlyList<TAggregate> aggregates);
40+
FinT<IO, int> UpdateRange(IReadOnlyList<TAggregate> aggregates);
41+
42+
// 호출자 사용 방식
43+
var created = await repository.CreateRange(orders).RunAsync();
44+
int count = created.ThrowIfFail(); // int (생성/업데이트된 행 수)
45+
```
46+
47+
**마이그레이션 가이드**:
48+
1. `CreateRange` / `UpdateRange` 반환값을 `Seq<TAggregate>`로 사용하는 모든 호출부를 `int`로 변경
49+
2. 배치 연산 후 Aggregate 컬렉션이 필요하면 입력 리스트를 직접 유지
50+
3. `CreateRange` 또는 `UpdateRange`를 override하는 커스텀 Repository 서브클래스의 반환 타입 업데이트
51+
52+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
53+
54+
---
55+
56+
### 2. EfCoreRepositoryBase 서브클래스에 새 추상 메서드 `BuildSetters` 필수
57+
58+
`EfCoreRepositoryBase`의 모든 서브클래스에서 `BuildSetters` 추상 메서드를 구현해야 합니다. 이 메서드는 `Update`/`UpdateRange` 연산에서 `ExecuteUpdateAsync`가 사용하는 `SetProperty` 매핑을 제공합니다.
59+
60+
**이전 (v1.0.0-alpha.2)**:
61+
```csharp
62+
public class OrderRepository : EfCoreRepositoryBase<Order, OrderId, OrderModel>
63+
{
64+
// ToDomain과 ToModel만 필수
65+
protected override Order ToDomain(OrderModel model) => ...;
66+
protected override OrderModel ToModel(Order aggregate) => ...;
67+
}
68+
```
69+
70+
**이후 (v1.0.0-alpha.3)**:
71+
```csharp
72+
public class OrderRepository : EfCoreRepositoryBase<Order, OrderId, OrderModel>
73+
{
74+
protected override Order ToDomain(OrderModel model) => ...;
75+
protected override OrderModel ToModel(Order aggregate) => ...;
76+
77+
// 신규: ExecuteUpdateAsync에 필수
78+
protected override void BuildSetters(
79+
UpdateSettersBuilder<OrderModel> setters, OrderModel model)
80+
=> OrderModel.ApplySetters(setters, model); // [GenerateSetters]가 생성
81+
}
82+
```
83+
84+
**마이그레이션 가이드**:
85+
1. EF Core 모델 클래스에 `[GenerateSetters]` 어트리뷰트를 적용하고 `partial`로 선언
86+
2. Repository 서브클래스에서 생성된 `ApplySetters`에 위임하는 `BuildSetters` 메서드 구현
87+
3. 프로젝트에 `Functorium.SourceGenerators` 참조 추가
88+
89+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
90+
91+
---
92+
93+
### 3. ExistsBySpec 이름 변경 및 public 승격
94+
95+
`EfCoreRepositoryBase`의 `protected ExistsBySpec` 메서드가 `Exists`로 이름이 변경되고 `public virtual`로 승격되어, 새로운 `IRepository.Exists` 계약을 구현합니다.
96+
97+
**이전 (v1.0.0-alpha.2)**:
98+
```csharp
99+
// protected 메서드 — Repository 서브클래스 내부에서만 사용 가능
100+
protected FinT<IO, bool> ExistsBySpec(Specification<TAggregate> spec)
101+
```
102+
103+
**이후 (v1.0.0-alpha.3)**:
104+
```csharp
105+
// IRepository 인터페이스의 public 메서드
106+
public virtual FinT<IO, bool> Exists(Specification<TAggregate> spec)
107+
```
108+
109+
**마이그레이션 가이드**:
110+
1. 모든 `ExistsBySpec` 호출을 `Exists`로 이름 변경
111+
2. Repository 서브클래스에서 `ExistsBySpec`을 호출하고 있었다면, 이제 `IRepository` 인터페이스에서 직접 사용 가능
112+
113+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
114+
115+
## 새로운 기능
116+
117+
### Functorium 라이브러리
118+
119+
#### 1. IRepository 인터페이스 재구성
120+
121+
`IRepository<TAggregate, TId>` 인터페이스가 4개의 명확한 책임 그룹으로 재설계되었습니다. 각 그룹은 일관된 반환 타입 규칙을 따릅니다: 단건 쓰기 연산은 LINQ 모나드 합성을 위해 Aggregate를 반환하고, 배치 쓰기 연산은 영향 받은 행 수를 반환하며, Specification 연산은 단일 SQL 문으로 실행됩니다.
122+
123+
```csharp
124+
public interface IRepository<TAggregate, TId> : IObservablePort
125+
where TAggregate : AggregateRoot<TId>
126+
where TId : struct, IEntityId<TId>
127+
{
128+
// -- Write: Single --
129+
FinT<IO, TAggregate> Create(TAggregate aggregate);
130+
FinT<IO, TAggregate> Update(TAggregate aggregate);
131+
FinT<IO, int> Delete(TId id);
132+
133+
// -- Write: Batch --
134+
FinT<IO, int> CreateRange(IReadOnlyList<TAggregate> aggregates);
135+
FinT<IO, int> UpdateRange(IReadOnlyList<TAggregate> aggregates);
136+
FinT<IO, int> DeleteRange(IReadOnlyList<TId> ids);
137+
138+
// -- Read --
139+
FinT<IO, TAggregate> GetById(TId id);
140+
FinT<IO, Seq<TAggregate>> GetByIds(IReadOnlyList<TId> ids);
141+
142+
// -- Specification --
143+
FinT<IO, bool> Exists(Specification<TAggregate> spec);
144+
FinT<IO, int> Count(Specification<TAggregate> spec);
145+
FinT<IO, int> DeleteBy(Specification<TAggregate> spec);
146+
}
147+
```
148+
149+
**왜 중요한가:**
150+
- 단건/배치/읽기/Specification 책임을 명확히 분리하여 인터페이스 탐색 시 인지 부하 감소
151+
- 배치 연산이 `Seq<TAggregate>` 대신 `int`를 반환하여 호출자가 이미 보유한 대규모 Aggregate 컬렉션의 불필요한 실체화 방지
152+
- Specification 기반 `Exists`, `Count`, `DeleteBy`는 각각 단일 SQL 문으로 실행(클라이언트 측 필터링 없음)되어 Repository를 통한 효율적인 Aggregate 수준 쿼리 가능
153+
- `UpdateBy(Specification, SetPropertyCalls)`는 의존성 방향 규칙(EF Core 타입은 Adapter 계층)을 준수하기 위해 인터페이스에서 의도적으로 제외
154+
155+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
156+
157+
---
158+
159+
#### 2. Specification 기반 Repository 연산: Exists, Count, DeleteBy
160+
161+
3개의 새로운 Specification 기반 메서드가 `IRepository`에 추가되어, 단일 SQL 문으로 변환되는 Aggregate 수준 조건부 쿼리가 가능합니다. `EfCoreRepositoryBase`와 `InMemoryRepositoryBase` 모두 구현을 제공합니다.
162+
163+
```csharp
164+
// 고객의 활성 주문 존재 여부 확인 (1 SQL: SELECT EXISTS)
165+
var spec = new ActiveOrdersByCustomerSpec(customerId);
166+
FinT<IO, bool> exists = repository.Exists(spec);
167+
168+
// 매칭되는 Aggregate 건수 (1 SQL: SELECT COUNT)
169+
FinT<IO, int> count = repository.Count(spec);
170+
171+
// Specification 기반 대량 삭제 (1 SQL: DELETE WHERE)
172+
var expiredSpec = new ExpiredOrdersSpec(cutoffDate);
173+
FinT<IO, int> deletedCount = repository.DeleteBy(expiredSpec);
174+
```
175+
176+
**왜 중요한가:**
177+
- 이 메서드들 없이는 존재 확인이나 건수 조회를 위해 매칭되는 모든 Aggregate를 메모리에 로드한 후 클라이언트 측에서 필터링해야 했음
178+
- 각 연산은 EF Core의 Expression 변환을 통해 단일 SQL 문으로 컴파일되어 데이터베이스 라운드트립 최소화
179+
- `DeleteBy`는 `ExecuteDeleteAsync`로 Change Tracker를 완전히 우회하여 엔티티 로드 없이 대량 삭제 처리
180+
- Specification 재사용: 동일한 `Specification<TAggregate>` 클래스가 `Exists`, `Count`, `DeleteBy` 및 기존 쿼리 인프라에서 모두 동작
181+
182+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
183+
184+
---
185+
186+
### Functorium.Adapters 라이브러리
187+
188+
#### 3. EF Core Update 성능: ExecuteUpdateAsync 도입
189+
190+
`EfCoreRepositoryBase`의 `Update`와 `UpdateRange`가 기존 `FindAsync` + `SetValues` 패턴 대신 EF Core의 `ExecuteUpdateAsync`를 사용합니다. Change Tracker 기반 업데이트에 필요했던 SELECT 라운드트립이 제거됩니다.
191+
192+
```csharp
193+
// 이전: 2 라운드트립 (SELECT + UPDATE)
194+
// var existing = await DbSet.FindAsync(id);
195+
// DbContext.Entry(existing).CurrentValues.SetValues(updated);
196+
197+
// 이후: 1 라운드트립 (UPDATE WHERE Id = @id)
198+
var model = ToModel(aggregate);
199+
int affected = await DbSet
200+
.Where(ByIdPredicate(aggregate.Id))
201+
.ExecuteUpdateAsync(s => BuildSetters(s, model));
202+
```
203+
204+
**왜 중요한가:**
205+
- `Update`가 2 데이터베이스 라운드트립에서 1로 감소 (사전 SELECT 불필요), 단건 업데이트 지연 시간 절반으로 단축
206+
- `UpdateRange`가 Change Tracker 대신 Aggregate별 `ExecuteUpdateAsync`를 실행하여 N+1 SELECT 문제 방지
207+
- Change Tracker 우회로 대규모 배치 시나리오에서 수정된 엔티티 추적에 의한 메모리 압력 제거
208+
- `protected UpdateBy(Specification, Action<UpdateSettersBuilder>)` 메서드를 통해 서브클래스에서 도메인 특화 조건부 대량 업데이트 구현 가능 (예: "만료된 구독 일괄 비활성화"를 단일 SQL UPDATE로 처리)
209+
210+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
211+
212+
---
213+
214+
#### 4. CreateRange 대량 데이터 청크 삽입
215+
216+
`CreateRange`가 대규모 입력을 감지하여 자동으로 청크로 분할하고, 청크별로 `SaveChangesAsync` + `ChangeTracker.Clear()`를 호출하여 메모리 부족을 방지합니다.
217+
218+
```csharp
219+
// 소량 배치 (<= IdBatchSize): 단일 AddRange + SaveChanges
220+
// 대량 배치 (> IdBatchSize): 청크 처리
221+
222+
// EfCoreRepositoryBase가 자동으로 처리:
223+
// foreach (var chunk in aggregates.Chunk(IdBatchSize))
224+
// {
225+
// DbSet.AddRange(chunk.Select(ToModel));
226+
// await DbContext.SaveChangesAsync();
227+
// DbContext.ChangeTracker.Clear();
228+
// }
229+
230+
// 사용법은 변경 없음:
231+
FinT<IO, int> created = repository.CreateRange(largeOrderList);
232+
```
233+
234+
**왜 중요한가:**
235+
- 단일 `AddRange` + `SaveChangesAsync` 호출로 수만 건의 엔티티를 삽입하면 Change Tracker 메모리가 무한히 증가하여 운영 환경에서 OOM 발생
236+
- `ChangeTracker.Clear()`를 사용한 청크 처리로 배치 크기에 관계없이 일정한 메모리 사용량 유지
237+
- 소량 배치(`IdBatchSize` 이하)는 청크 오버헤드 없이 빠른 동기 경로 사용
238+
- 청크 간 원자성을 보장하려면 `UsecaseTransactionPipeline` 컨텍스트 내에서 사용해야 함; 래핑 트랜잭션 없이는 부분 삽입 롤백 불가
239+
240+
<!-- 관련 커밋: 5d843dab feat!(repository): IRepository 재설계 및 EF Core 대량 처리 성능 개선 -->
241+
242+
---
243+
244+
#### 5. [GenerateSetters] Source Generator
245+
246+
EF Core 모델 클래스에 새로운 `[GenerateSetters]` 어트리뷰트를 적용하면 Source Generator가 `ExecuteUpdateAsync`용 각 settable 프로퍼티를 `SetProperty` 호출로 매핑하는 `ApplySetters` 정적 메서드를 생성합니다.
247+
248+
```csharp
249+
using Functorium.Adapters.SourceGenerators;
250+
251+
[GenerateSetters]
252+
public partial class OrderModel : IHasStringId
253+
{
254+
public string Id { get; set; } = string.Empty; // 자동 제외 (Id)
255+
public string Status { get; set; } = string.Empty;
256+
public decimal TotalAmount { get; set; }
257+
258+
[SetterIgnore]
259+
public DateTime AuditTimestamp { get; set; } // 수동 제외
260+
261+
public ICollection<OrderItemModel> Items { get; set; } = []; // 자동 제외 (네비게이션)
262+
}
263+
264+
// 생성된 메서드 (Functorium.SourceGenerators에 의해):
265+
// public static void ApplySetters(UpdateSettersBuilder<OrderModel> s, OrderModel m)
266+
// {
267+
// s.SetProperty(x => x.Status, m.Status);
268+
// s.SetProperty(x => x.TotalAmount, m.TotalAmount);
269+
// }
270+
271+
// Repository에서 사용:
272+
protected override void BuildSetters(
273+
UpdateSettersBuilder<OrderModel> setters, OrderModel model)
274+
=> OrderModel.ApplySetters(setters, model);
275+
```
276+
277+
**왜 중요한가:**
278+
- 각 모델 프로퍼티에 대해 수동으로 `SetProperty` 호출을 작성하는 것은 번거롭고 실수하기 쉬움; 새 컬럼을 추가하면 모델과 Repository 양쪽을 업데이트해야 함
279+
- Source Generator가 모델과 자동으로 `ApplySetters`를 동기화 — 프로퍼티를 추가하면 빌드 타임에 setter 매핑이 생성됨
280+
- `Id` 프로퍼티와 네비게이션 프로퍼티(`ICollection<T>`, `IList<T>`)가 자동으로 제외되어 실수로 인한 기본 키 덮어쓰기나 네비게이션 에러 방지
281+
- `[SetterIgnore]`로 감사 컬럼이나 계산 필드 등 업데이트에 포함되지 않아야 하는 프로퍼티를 세밀하게 제어
282+
283+
<!-- 관련 커밋: 606e610e feat(source-gen): [GenerateSetters] Source Generator 추가 -->
284+
285+
## 버그 수정
286+
287+
- IRepository 재설계 후 BulkCrud 벤치마크 네임스페이스 및 `ValidationRules<T>` 참조 수정 (`8d4e1b8a`)
288+
289+
## API 변경사항
290+
291+
### IRepository 인터페이스 (Functorium)
292+
293+
```
294+
Functorium.Domains.Repositories
295+
└── IRepository<TAggregate, TId>
296+
├── Write: Single
297+
│ ├── Create(TAggregate) -> FinT<IO, TAggregate>
298+
│ ├── Update(TAggregate) -> FinT<IO, TAggregate>
299+
│ └── Delete(TId) -> FinT<IO, int>
300+
├── Write: Batch
301+
│ ├── CreateRange(IReadOnlyList<TAggregate>) -> FinT<IO, int> [변경: 기존 Seq<TAggregate>]
302+
│ ├── UpdateRange(IReadOnlyList<TAggregate>) -> FinT<IO, int> [변경: 기존 Seq<TAggregate>]
303+
│ └── DeleteRange(IReadOnlyList<TId>) -> FinT<IO, int>
304+
├── Read
305+
│ ├── GetById(TId) -> FinT<IO, TAggregate>
306+
│ └── GetByIds(IReadOnlyList<TId>) -> FinT<IO, Seq<TAggregate>>
307+
└── Specification [신규 그룹]
308+
├── Exists(Specification<TAggregate>) -> FinT<IO, bool> [신규]
309+
├── Count(Specification<TAggregate>) -> FinT<IO, int> [신규]
310+
└── DeleteBy(Specification<TAggregate>) -> FinT<IO, int> [신규]
311+
```
312+
313+
### EfCoreRepositoryBase 신규 멤버 (Functorium.Adapters)
314+
315+
```
316+
Functorium.Adapters.Repositories
317+
└── EfCoreRepositoryBase<TAggregate, TId, TModel>
318+
├── abstract void BuildSetters(UpdateSettersBuilder<TModel>, TModel) [신규: 필수]
319+
├── virtual FinT<IO, bool> Exists(Specification<TAggregate>) [신규: 기존 protected ExistsBySpec]
320+
├── virtual FinT<IO, int> Count(Specification<TAggregate>) [신규]
321+
├── virtual FinT<IO, int> DeleteBy(Specification<TAggregate>) [신규]
322+
└── protected FinT<IO, int> UpdateBy(Specification<TAggregate>, Action<UpdateSettersBuilder<TModel>>) [신규]
323+
```
324+
325+
### Source Generator 어트리뷰트 (Functorium.Adapters)
326+
327+
```
328+
Functorium.Adapters.SourceGenerators
329+
├── GenerateSettersAttribute [신규]
330+
└── SetterIgnoreAttribute [신규]
331+
```
332+
333+
## 설치
334+
335+
### NuGet 패키지 설치
336+
337+
```bash
338+
# Functorium 핵심 라이브러리
339+
dotnet add package Functorium --version 1.0.0-alpha.3
340+
341+
# Functorium.Adapters (Repository, Pipeline, Observability)
342+
dotnet add package Functorium.Adapters --version 1.0.0-alpha.3
343+
344+
# Functorium.SourceGenerators (빌드 타임 코드 생성)
345+
dotnet add package Functorium.SourceGenerators --version 1.0.0-alpha.3
346+
347+
# Functorium.Testing (테스트 유틸리티, 선택)
348+
dotnet add package Functorium.Testing --version 1.0.0-alpha.3
349+
```
350+
351+
### 필수 의존성
352+
353+
- .NET 10 이상
354+
- LanguageExt.Core 5.x
355+
- Microsoft.EntityFrameworkCore.Relational (`ExecuteUpdateAsync` 필수)

0 commit comments

Comments
 (0)