Common > Status Code: 비트에 의미를 담은 상태 코드 공급기 구현 #65

merge-simpson · 2025-05-01T14:49:39Z

Pull Request

Issues

Resolves [MAIN] Semantic Status Code 운영을 위한 파라미터 클래스 생성 #55

Description

우리가 사용할 3개 주요 아이템 작업에 집중해 주시면 좋습니다.

1. Type-Safe Markers

JDK 17 sealed 인터페이스와 마커 클래스를 만들어 활용합니다.

public sealed interface TypeSafeMarker permits TypeSafeMarker.Present, TypeSafeMarker.Missing {
    final class Present implements TypeSafeMarker { private Present() {} }
    final class Missing implements TypeSafeMarker { private Missing() {} }
}

2, 3. Entity Status Code

Sign Bit	General Purpose Bits	System Info Bits	Category Bits	Instance Detail Bits
1 bit (ø)	7 bits	8 bits	8 bits	8 bits

Example Use Case

var parameters = StatusParameters.generate()
        .generalPurposeFeatures(
                GeneralPurposeFeatures.READ,
                GeneralPurposeFeatures.UPDATE
        )
        .systemInfoBits(0)
        .categoryBits(0)
        .instanceBits(0);

int code = StatusCodeUtil.getAsInt(parameters);

StatusParameters: 의미를 담은 코드 값을 생성하는 기본 전략을 적용한 파라미터 객체입니다.

(참고) 다음 열거 상수를 포함합니다.

public enum GeneralPurposeFeatures {
    ALL(0b110_1100),
    READ(0b100_0000),
    UPDATE(0b010_0000),
    SUBITEM_READ(0b000_1000),
    SUBITEM_UPDATE(0b000_0100);

    private final int bit;

    GeneralPurposeFeatures(int bit) {
        this.bit = bit;
    }
}

StatusCodeUtil: 이하 StatusParameters 인스턴스를 정수 코드 값으로 산출해 줍니다.
- 필수 입력 필드를 채운 StatusParameters 인스턴스만 입력받습니다. (제네릭 활용)

Others

이하 항목은 각 비트 섹션의 크기를 커스텀할 수 있도록 추가한 long 타입 코드 생성 클래스들입니다.
코드리뷰에서 집중하지 않아도 되는 부분이라고 생각합니다.

CustomStatusParameters
CustomStatusParametersSupplier

How Has This Been Tested?

Kotest FreeSpec
StatusCodeUtilTest에서 StatusParameters 테스트를 겸했습니다.
각 섹션에 대한 독립적인 테스트 항목만 포함했습니다.

Additional Notes

자세한 설명은 다음 페이지를 참고하세요:

See Details (Click): https://nettee.notion.site/2025-type-safe-builder Entity Status Code 설명

Dynamic Generated Test: 많은 경우의 수를 테스트하기 위해 Pair List를 활용했습니다.

General Purpose 기능 목록은 다양한 조합을 모두 테스트하기 위해 동적으로 테스트를 생성했습니다.

val cases = listOf(
    setOf(READ) to 0x40_00_00_00,
    setOf(UPDATE) to 0x20_00_00_00,
    setOf(SUBITEM_READ) to 0x08_00_00_00,
    setOf(SUBITEM_UPDATE) to 0x04_00_00_00,
    setOf(READ, UPDATE) to 0x60_00_00_00,
    setOf(READ, SUBITEM_READ) to 0x48_00_00_00,
    // ...
    setOf(READ, SUBITEM_READ, SUBITEM_UPDATE) to 0x4C_00_00_00,
    setOf(UPDATE, SUBITEM_READ, SUBITEM_UPDATE) to 0x2C_00_00_00,
)

cases.forEach { (features, expectedCode) ->
    "GP: ${features.joinToString()}" {
        val parameters = StatusParameters.generate()
            .generalPurposeFeatures(*features.toTypedArray())
            .systemInfoBits(0)
            .categoryBits(0)
            .instanceBits(0)

        val code = StatusCodeUtil.getAsInt(parameters)

        code shouldBe expectedCode
    }
}

…ters`

…plier

…h local variables 일부 필드가 지역적으로만 사용되기 때문에 개선합니다.

… in `CustomStatusParameters`

…StatusCodeUtil` - `StatusCodeUtil.getAsLong(CustomStatusParameters<Present, Present>)`

wch-os

@merge-simpson 님 복잡한 설계 방식을 모두가 이해할 수 있도록 정리해주셔 한결 편하게 읽을 수 있었습니다! 정말 감사드립니다!!

코드를 리뷰하면서 몇 가지 궁금한 점이 있어 질문드립니다!

Q1. StatusParameters로 관리할 만큼 enum 인스턴스들이 여러 파라미터가 필요한지 궁금합니다.

Q2. 위 설계는 컴파일 타임에 일부 파라미터가 누락되는 것을 방지하기 위한 패턴으로 이해했습니다! 하지만 enum 특성상 모든 인스턴스에 미리 정의가 되어, static 블록에서의 유효성 검증으로도 충분히 누락 방지가 가능하지 않을까 의문이 들었습니다. 이 부분에 대해서도 의견이 있으신지 궁금합니다!

merge-simpson · 2025-05-14T02:05:53Z

@wch-os 님, 예리하고 좋은 질문 감사합니다!

Origin question

댓글 보기 (click)

@merge-simpson 님, 복잡한 설계 방식을 모두가 이해할 수 있도록 정리해 주셔 한결 편하게 읽을 수 있었습니다! 정말 감사드립니다!!

코드를 리뷰하면서 몇 가지 궁금한 점이 있어 질문드립니다!

Q1. StatusParameters로 관리할 만큼 enum 인스턴스들이 여러 파라미터가 필요한지 궁금합니다.

Q2. 위 설계는 컴파일 타임에 일부 파라미터가 누락되는 것을 방지하기 위한 패턴으로 이해했습니다! 하지만 enum 특성상 모든 인스턴스가 미리 정의가 되어, static 블록에서의 유효성 검증으로도 충분히 누락 방지가 가능하지 않을까 의문이 들었습니다. 이 부분에 대해서도 의견이 있으신지 궁금합니다!

Answer

Q1. StatusParameters로 관리할 만큼 enum 인스턴스들이 여러 파라미터가 필요한지 궁금합니다.

반드시 그런 것은 아닙니다. 이 StatusCode를 사용하는 이유는 다음과 같습니다.

DB에 종속적인 관리 전략

DB 접속부 코드: 도메인 status가 아니라 DB 연결부(ORM 등) entity status에만 사용합니다.
성능: 조회 등 접근 성능에 긍정적인 영향을 위해 추가된 코드가 있습니다.

각 비트 필드의 역할

부호 비트를 제외하고, 총 4개 구간으로 구분하였습니다.

General purpose 비트 필드는 비교적 상위 비트(왼쪽 비트, 큰 값)를 활용했습니다.
System information 비트 필드 등 일부 필드는 분산 환경의 관리 전략에 조금 더 유연성을 제공합니다.
Classifying 비트 필드 및 인스턴스 디테일 비트 필드를 모두 사용하는 것은 밀접하게 관련된 상태를 분류하면서도 상세하게 구분할 수 있게 해 줍니다. 관련 설명 블록 (Notion)

Q2. 위 설계는 컴파일 타임에 일부 파라미터가 누락되는 것을 방지하기 위한 패턴으로 이해했습니다! 하지만 enum 특성상 모든 인스턴스가 미리 정의가 되어, static 블록에서의 유효성 검증으로도 충분히 누락 방지가 가능하지 않을까 의문이 들었습니다. 이 부분에 대해서도 의견이 있으신지 궁금합니다!

필요성

말씀대로 필수적이지 않습니다.
StatusParameters는 단지 우리가 코드를 '읽을 수 있게' 만들어 주어 유용합니다. (실수 감소)
Type-safe builder는 이전 실습 때 간략하게 언급한 대로 '굳이 적용할 필요는 없지만, 예시로 적절한 타이밍이라서' 적용했습니다. 또한 굳이 제외할 이유가 없어 유지하고 있습니다.

sweetykr7

잘 구조화된 설계와 타입 안전성을 높이기 위한 시도가 인상적입니다.
특히 Type-Safe Marker 패턴을 활용해 "필수 필드가 채워졌는지"를 컴파일 타임에 강제하도록 설계된 점이 매우 인상 깊었고,
비트 구조를 통해 정교하게 상태 코드를 조립하는 Entity Status Code 전략도 응집력 있게 잘 구성되어 있습니다.

코드를 보면서 마치 리눅스의 chmod 명령어처럼,
비트 조합을 통해 권한이나 상태를 관리할 수 있다는 점이 흥미로웠습니다.
고생하셨습니다!

merge-simpson added 16 commits April 29, 2025 23:15

feat(common): add type-safe markers (Present, Missing)

5f62791

fix(board): use type-safe markers of common module

9705127

feat(common): add StatusParameters for status code

bff9a82

feat(common): add StatusCodeUtil calculating code via `StatusParame…

223058c

…ters`

refactor(common): add constants about status code

ec69f40

refactor(common): make constants depend on other constants

364c633

feat(common): add status code exception, error codes

2f0fbd9

refactor(common): reorder constants of status code error code

fd0f4e2

feat(common): append status code error codes

4415682

feat(common): add long type custom status code parameters and its sup…

78d836d

…plier

chore(common): remove useless comment

8aa819d

docs(common): explain custom status parameters

9973187

build(common): add test implementations

aedc9b7

test(common): test status code GP bits

d02aea5

test(common): test status code system info bits

b55cc18

test(common): test status code category, instance detail bits

c72f0d7

merge-simpson added in: common Issues in the common module review: required Reviews are required type: feature 새로운 기능 또는 기능적 개선 A new feature or enhancement labels May 1, 2025

merge-simpson requested review from wowddok99, jilpoom, sweetykr7, silberbullet, Ropung, wch-os, seonghooni and taewookimm May 1, 2025 14:49

merge-simpson self-assigned this May 1, 2025

merge-simpson added 2 commits May 1, 2025 23:55

test(common): refactor status code util test with dynamic-generated test

fefea45

chore(common): format code style StatusCodeErrorCode

dca9740

merge-simpson added 6 commits May 1, 2025 23:59

chore(common): todo in StatusCodeUtil

de3f19c

refactor(common): replace some fields of CustomStatusParameters wit…

15180a4

…h local variables 일부 필드가 지역적으로만 사용되기 때문에 개선합니다.

feat(common): add methods to get gp shift, sys info shift, cate shift…

9b53ab8

… in `CustomStatusParameters`

feat(common): get long status code from CustomStatusParameters in `…

31f88ac

…StatusCodeUtil` - `StatusCodeUtil.getAsLong(CustomStatusParameters<Present, Present>)`

build(common): test implementation "spring-web"

cc2e30b

test(common): test CustomStatusParameters with StatusCodeUtil

b0e4b8a

wch-os reviewed May 11, 2025

View reviewed changes

merge-simpson added review: ing Reviews are in progress and taking time and removed review: required Reviews are required labels May 17, 2025

sweetykr7 approved these changes May 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Common > Status Code: 비트에 의미를 담은 상태 코드 공급기 구현 #65

Common > Status Code: 비트에 의미를 담은 상태 코드 공급기 구현 #65

merge-simpson commented May 1, 2025 •

edited

Loading

wch-os left a comment •

edited

Loading

merge-simpson commented May 14, 2025

sweetykr7 left a comment

Common > Status Code: 비트에 의미를 담은 상태 코드 공급기 구현 #65

Are you sure you want to change the base?

Common > Status Code: 비트에 의미를 담은 상태 코드 공급기 구현 #65

Conversation

merge-simpson commented May 1, 2025 • edited Loading

Pull Request

Issues

Description

1. Type-Safe Markers

2, 3. Entity Status Code

Others

How Has This Been Tested?

Additional Notes

자세한 설명은 다음 페이지를 참고하세요:

Dynamic Generated Test: 많은 경우의 수를 테스트하기 위해 Pair List를 활용했습니다.

wch-os left a comment • edited Loading

Choose a reason for hiding this comment

merge-simpson commented May 14, 2025

Origin question

Answer

sweetykr7 left a comment

Choose a reason for hiding this comment

merge-simpson commented May 1, 2025 •

edited

Loading

wch-os left a comment •

edited

Loading