GN2.Core 3.0.0

GN2.Core

GN2 계열 .NET 시스템의 공유 커널입니다. 인증서버(OpenIddict)와 모든 클라이언트가 함께 참조하는, 가장 아래 계층의 라이브러리입니다.

• Target Framework: net10.0 · Version: 3.0.0 · NuGet: GN2.Core
• 외부 NuGet 의존성 없음

설계 원칙

1. 의존성 0 — 어떤 프로젝트가 참조해도 전이 의존성이 생기지 않습니다.
2. I/O 없음 — 네트워크·파일·DB에 접근하지 않습니다. HttpClient를 쓰는 코드는 이 패키지에 두지 않습니다 (GN2.Business 담당).
3. 프레임워크 중립 — ASP.NET Core, EF Core, Swagger에 의존하지 않습니다.
4. 트리밍 · Native AOT 호환

패키지 관계

GN2.Core                도메인 · 계약 · 프로토콜 상수
  ├─ GN2.Business          OIDC 통신 + ASP.NET Core 인증 · 인가
  ├─ GN2.Common.Library    암호화, 메일, ActionBridge
  └─ GN2.Common.Web        Swagger, API 버저닝, EF Core 확장

OpenIddict 인증서버 → GN2.Core 만 참조하면 됩니다.

구성

Identity/        JwtClaimTypes, OidcConstants
Models/          ReturnValue, ReturnValues, AuditableEntity, BaseEntity, ConditionStatus
Models/Paging/   PagingBase, PagingParameter, SearchParameter
Configurations/  ExternalApi / Site / Identity / SMTP 설정 레코드
Abstracts/       IHasAuditableEntity, IPagingBase
Extends/         Are, ExtendObject, ExtendQueryable, JsonHelper
Helpers/         DateTimeHelper, StringHelper, ValidateHelper
ErrorHandling/   RestException
Filters/         StringValueAttribute

Identity — 서버와 클라이언트의 단일 출처

JwtClaimTypes와 OidcConstants의 값은 OpenIddict의 OpenIddictConstants 및 관련 RFC와 일치합니다.

using GN2.Core.Identity;

// 인증서버 (OpenIddict)
identity.AddClaim(JwtClaimTypes.Role, "Admin")
        .SetDestinations(OidcConstants.Destinations.AccessToken);

options.RegisterScopes(OidcConstants.Scopes.OpenId,
                       OidcConstants.Scopes.Profile,
                       OidcConstants.Scopes.OfflineAccess);

// 클라이언트
var subject = user.FindFirst(JwtClaimTypes.Subject)?.Value;
var roles   = user.FindAll(JwtClaimTypes.Role).Select(c => c.Value);

OidcConstants 안에 GrantTypes, Scopes, Destinations, CodeChallengeMethods, ResponseTypes, ResponseModes, Prompts, ClientAuthenticationMethods, TokenTypeHints, Algorithms, Parameters, Errors, Discovery, Endpoints가 있습니다.

⚠️ 클레임 이름 매핑을 반드시 끄세요

JwtBearerOptions.MapInboundClaims는 **기본값이 true**라서, 토큰의 sub·role이 WS-Federation URI로 바뀐 채 들어옵니다. 그러면 위의 FindFirst(JwtClaimTypes.Role)이 아무것도 찾지 못합니다.

options.MapInboundClaims = false;
options.TokenValidationParameters.NameClaimType = JwtClaimTypes.Subject;
options.TokenValidationParameters.RoleClaimType = JwtClaimTypes.Role;

GN2.Business의 RegisterAuthentication은 이 설정을 기본으로 적용합니다.

JwtClaimTypes.ClientRole("client_role")은 표준이 아니라 Duende IdentityServer 관례입니다. OpenIddict에는 대응 개념이 없습니다.

감사 상태 — 행위 메서드로 전이

setter를 직접 건드리지 마세요. 아래 메서드가 상태·사용여부·작업자·시각을 한 번에 갱신합니다.

var condition = AuditableEntity.Create(userId);   // 생성

condition.MarkUpdated(userId);   // 수정
condition.MarkDraft(userId);     // 초안 (Hidden)
condition.Publish(userId);       // 공개 (Active)
condition.Disable(userId);       // 비활성 (Disabled)
condition.MarkDeleted(userId);   // 논리 삭제 (Out)
condition.Restore(userId);       // 복구

condition.IsPublicVisible;       // IsEnabled && Status == Active
condition.IsDraft;
condition.IsRemoved;

시각은 UTC로 기록합니다. 테스트에서 고정하려면 TimeProvider를 넘기세요.

condition.MarkDeleted(userId, fakeTimeProvider);

EF Core 매핑과 상태별 조회 필터는 GN2.Common.Web.EntityFramework에 있습니다.

응답 계약

var result = new ReturnValues<Order>();

try
{
    result.SetSuccess(1, await repository.GetAsync(id));
}
catch (Exception ex)
{
    result.SetError(ex);
    logger.LogError(ex, "{Diag}", result.ToDiagnosticString());
}

팩토리도 있습니다.

return order is null
    ? ReturnValues<Order>.Fail("주문을 찾을 수 없습니다.", errorCode: 404)
    : ReturnValues<Order>.Ok(order);

Message는 호출자에게 노출되는 값입니다. 예외 객체는 직렬화되지 않는 Exception 속성에만 담기므로 스택 트레이스가 응답으로 새지 않습니다.

페이징 계약

public record OrderSearch : SearchParameter
{
    public string? Status { get; init; }
}

var items = await query
    .WhereIf(!string.IsNullOrWhiteSpace(p.Keyword), x => x.Title.Contains(p.Keyword!))
    .Skip((p.CurPage - 1) * p.PageSize)
    .Take(p.PageSize)
    .ToListAsync();

페이지 번호 블록과 이동 URL(PagingHelper)은 GN2.Common.Web.Models.Paging에 있습니다.

트리밍 · Native AOT

패키지 전체가 IsAotCompatible로 빌드되며 경고가 없습니다. 리플렉션을 쓰는 두 곳만 명시적으로 표시되어 있습니다.

• ExtendObject — [DynamicallyAccessedMembers]로 필요한 멤버를 보존
• JsonHelper.Serialize/Deserialize<T> — [RequiresUnreferencedCode] 표시. AOT 게시 시에는 JsonTypeInfo<T> 오버로드를 쓰세요

var json = JsonHelper.Serialize(order, AppJsonContext.Default.Order);

2.x → 3.0.0 마이그레이션

다른 패키지로 이동

이름 변경

제거

AzureBlobSettings, ApplicationInsights, RedisConfiguration, HostSettings, DatabaseConnectionStrings, ClientConfiguration, SiteInfo, EntityHelper, FileHelper, RandomHelper, CalendarHelper, StringHelper.GetYoutubeThumbnailURL

RandomHelper는 System.Random 기반이라 토큰·인증 코드 생성에 쓰면 안 되는 물건이었습니다. 보안 용도라면 RandomNumberGenerator를 쓰세요.

동작 변경

• ReturnValue.SetError(Exception)이 더 이상 스택 트레이스를 Message에 넣지 않습니다 → ToDiagnosticString() 사용
• ReturnValues<T>에서 Data를 설정하지 않는 SetSuccess 오버로드는 컴파일 경고가 납니다
• ReturnValues<T>(T data) 생성자가 이제 데이터를 저장합니다
• StringHelper.SpaceSplitList가 중복 값에서 예외를 던지지 않습니다

버전 정책

SemVer를 따릅니다. ConditionStatus의 숫자 값은 영속화되므로 변경하지 않습니다.

3.0.0 배포 후 GN2.Core.csproj의 EnablePackageValidation 주석을 해제하면, 그 시점부터 공개 API를 깨는 변경이 빌드 오류로 잡힙니다.

라이선스

Apache License 2.0