GN2.Common.Library 3.0.0

GN2.Common.Library

GN2.Common.Library 는 GN2.Core 를 사용하는 프로젝트가 반복해서 구현하는 일들을 모아둔 범용 유틸리티 패키지입니다. 웹 프레임워크에 의존하지 않으므로 API 서버, 워커, 콘솔 앱에서 똑같이 사용할 수 있습니다.

패키지 정보

• Target Framework: net10.0
• Version: 3.0.0
• NuGet: GN2.Common.Library
• 의존성: GN2.Core, Microsoft.Extensions.DependencyInjection.Abstractions, Microsoft.Extensions.Logging.Abstractions, Microsoft.Extensions.Options

구성

Abstracts/  IActionBridge · IBridgeRequest · IBridgeHandler · IBridgeBehavior
            IObjectLinker · MappingExpression
            IEmailSender · EmailMessage
            ISecretProtector · IPasswordHasher
Bridge/     ActionBridge, AddActionBridge
Mapping/    ObjectLinker, AddObjectLinker
Security/   AesGcmSecretProtector, Pbkdf2PasswordHasher, HashText, Base64UrlText
Mail/       SmtpEmailSender, AddSmtpEmailSender
Text/       HtmlText

ActionBridge — 요청 디스패처

요청 하나에 핸들러 하나를 대응시키고, 필요하면 파이프라인으로 감쌉니다.

using GN2.Common.Library.Abstracts;
using GN2.Common.Library.Bridge;

services.AddActionBridge(options =>
{
    options.RegisterServicesFromAssemblyContaining<Program>();
    options.AddOpenBehavior(typeof(LoggingBehavior<,>));
});

public sealed record GetArticle(long Id) : IBridgeRequest<ReturnValues<ArticleModel>>;

public sealed class GetArticleHandler : IBridgeHandler<GetArticle, ReturnValues<ArticleModel>>
{
    public async Task<ReturnValues<ArticleModel>> HandleAsync(GetArticle request, CancellationToken cancellationToken = default)
    {
        // ...
    }
}

var result = await bridge.SendAsync(new GetArticle(10), cancellationToken);

파이프라인 동작은 등록한 순서대로 바깥에서 안쪽으로 실행됩니다.

public sealed class LoggingBehavior<TRequest, TResponse> : IBridgeBehavior<TRequest, TResponse>
    where TRequest : IBridgeRequest<TResponse>
{
    private readonly ILogger<LoggingBehavior<TRequest, TResponse>> _logger;

    public LoggingBehavior(ILogger<LoggingBehavior<TRequest, TResponse>> logger) => _logger = logger;

    public async Task<TResponse> HandleAsync(TRequest request, BridgeHandlerDelegate<TResponse> next, CancellationToken cancellationToken = default)
    {
        _logger.LogDebug("{Request} 처리 시작", typeof(TRequest).Name);
        var response = await next(cancellationToken);
        _logger.LogDebug("{Request} 처리 완료", typeof(TRequest).Name);
        return response;
    }
}

• 요청 타입 하나에 핸들러는 하나만 등록할 수 있습니다. 둘 이상 발견되면 등록 시점에 예외가 발생합니다.
• AddActionBridge 는 여러 번 호출해도 중복 등록되지 않습니다.
• 핸들러 수명은 기본 Transient, IActionBridge 는 기본 Scoped 이며 옵션으로 바꿀 수 있습니다.

ObjectLinker — 경량 객체 매퍼

이름이 같고 타입이 호환되는 속성은 규약으로 복사하고, 나머지는 명시적으로 지정합니다.

using GN2.Common.Library.Mapping;

services.AddObjectLinker(options =>
{
    options.CreateMap<Article, ArticleModel>()
           .ForMember(d => d.UserName, s => s.User.FullName)
           .ForMember(d => d.LocalizedUrls, s => s.Translations.Where(t => t.IsConfirmed).ToList())
           .Ignore(d => d.InternalMemo);
});

var model = linker.Map<Article, ArticleModel>(article);
var models = linker.MapMany<Article, ArticleModel>(articles);

• 매핑 계획은 타입 쌍마다 한 번만 계산되고 인스턴스 단위로 캐시됩니다.
• 규약 매핑은 같은 이름 + 대입 가능한 타입(값 타입 T → T? 포함)일 때 적용됩니다. 숫자 암시 변환(int → long)은 매핑하지 않습니다.
• 대상 속성이 없거나 쓰기 불가능하면 ForMember 구성 시점에 예외가 발생합니다.
• 대상 타입은 참조 타입이어야 하며 매개변수 없는 생성자가 필요합니다.

Security — 암호화 · 해시

문자열 보호 (AES-256-GCM)

using GN2.Common.Library.Abstracts;
using GN2.Common.Library.Security;

services.AddSecretProtector(options =>
{
    options.Passphrase = configuration["Security:Passphrase"]; // 보안 저장소에서 주입
    options.Salt = "gn2-article-v1";                           // 애플리케이션 고정값
});

var token = protector.Protect("010-0000-0000");
if (protector.TryUnprotect(token, out var phone))
{
    // ...
}

• 결과는 URL·쿼리스트링에 그대로 넣을 수 있는 Base64Url 문자열입니다.
• 메시지마다 임의 nonce 를 사용하므로 같은 평문도 매번 다른 값이 됩니다. 보호된 값을 조회 키로 쓸 수 없습니다. 검색이 필요하면 HashText.Sha256Hex 로 만든 별도 컬럼을 사용하세요.
• 인증 태그로 변조를 감지합니다. 손상되거나 위조된 값은 TryUnprotect 가 false 를 반환합니다.
• Salt 나 Passphrase 를 바꾸면 기존 값을 복호화할 수 없습니다.

비밀번호 해시 (PBKDF2-HMAC-SHA512)

services.AddPasswordHasher();

var stored = hasher.Hash(password);        // pbkdf2-sha512$210000$...$...
var isValid = hasher.Verify(password, stored);
if (isValid && hasher.NeedsRehash(stored))
{
    // 반복 횟수 정책이 올라갔다면 로그인 성공 시점에 다시 저장
}

반복 횟수가 해시 문자열에 포함되므로, 정책을 올려도 기존 해시를 그대로 검증할 수 있습니다.

해시 · 인코딩

HashText.Sha256Hex("text");                       // 체크섬 · 캐시 키 · 조회용 해시
HashText.HmacSha256Hex(payload, secretKey);       // 웹훅 서명
HashText.FixedTimeEquals(signature, expected);    // 타이밍 공격 방지 비교

Base64UrlText.EncodeText("한글도 안전합니다");
Base64UrlText.TryDecode(token, out var bytes);

HashText 는 비밀번호 저장에 사용하지 않습니다. 비밀번호는 반드시 IPasswordHasher 를 사용하세요.

Mail — SMTP 발송

using GN2.Common.Library.Mail;

services.AddSmtpEmailSender(options => configuration.GetSection("Smtp").Bind(options));

await sender.SendHtmlAsync("user@example.com", "가입을 환영합니다", html, cancellationToken);

await sender.SendAsync(new EmailMessage
{
    Subject = "월간 리포트",
    To = new[] { "user@example.com" },
    Bcc = new[] { "archive@example.com" },
    HtmlBody = html,
    TextBody = text,
}, cancellationToken);

SmtpConfiguration 은 GN2.Core.Configurations 에 있습니다. 로그에는 수신자 수와 결과만 남고 주소·본문은 남지 않습니다.

Text — HTML 헬퍼

using GN2.Common.Library.Text;

var summary = HtmlText.Summarize(article.Content, 120);
var thumbnail = HtmlText.ExtractFirstImageSource(article.Content);
var plain = HtmlText.StripTags(article.Content);
var body = HtmlText.ToHtmlLineBreaks(comment.Content);

정규식 기반이므로 편집기 산출물 같은 단순한 마크업을 대상으로 합니다. StripTags 는 요약·색인용이며 XSS 방어용 새니타이저가 아닙니다.

2.x 에서 올라올 때

CORS 는 프레임워크 기본 API 로 대체합니다.

services.AddCors(options => options.AddDefaultPolicy(policy =>
    policy.WithOrigins(allowedHosts).AllowAnyHeader().AllowAnyMethod()));

사용 시 주의

• ActionBridge 와 ObjectLinker 는 런타임 리플렉션을 사용하므로 트리밍 · Native AOT 경로에서는 사용하지 않습니다. Security · Mail · Text 는 리플렉션을 사용하지 않습니다.
• AddSecretProtector · AddPasswordHasher 는 구성 오류를 등록 시점에 예외로 알립니다.
• Passphrase 같은 비밀 값은 appsettings.json 이 아니라 환경 변수나 보안 저장소에서 주입하세요.