본문으로 건너뛰기

계약 중심 거래

거래의 사전적 의미는 '주고 받는 것 또는 사고 파는 것'이지만 처리 방식 또는 업무에 따라 차이가 있습니다. 예를 들어 거래를 영어 단어로 Transaction로 표현하며, 일반적으로 돈이나 물건을 주고 받는 것을 의미하지만, IT 업계의 데이터베이스 분야에서는 데이터의 상태를 변화시키기 위해 수행하는 논리적인 작업 단위를 의미합니다.

HandStack은 거래의 의미를 출발지와 도착지간의 시스템 간 거래에 사용되는 헤더(설명)과 바디(정보)로 구성된 메시지 구조를 주고 받는 작업 단위를 정의합니다. 이에 대해 화면 및 업무 개발자나 엔지니어가 소통하기 위해 다음과 같이 표현할 수 있습니다.

  • 클라이언트에서 업무 서버간에 거래를 합니다.
  • 업무 서버에서 어플리케이션 서버간에 거래를 합니다.
  • 어플리케이션 서버에서 데이터베이스 서버간에 거래를 합니다.
  • 어플리케이션 서버에서 외부 서비스간에 거래를 합니다.

다양한 시스템 간 거래를 위해 클라이언트와 서버간에는 반드시 어떻게 요청과 응답이 이뤄질 것인지 JSON/XML 포맷으로 되어진 계약을 정의 해야 합니다.

각 시스템간의 요청/응답 거래가 정상적으로 이뤄졌는지 아닌지에 따라 어느 구간에서 거래 에 이슈가 있는지 일관된 방식으로 처리를 하기 때문에 개발자와 엔지니어는 메시지 구조에 대해 알아두면 좋습니다.

transact 모듈 거래 전문 프로토콜​

HandStack 기반의 모든 거래 메시지는 transact 모듈에 있는 하나의 Endpoint에서 처리합니다. 그래서 올바른 요청과 정확한 응답에 대한 처리를 검증하기 위한 계약 정보를 JSON 파일로 정의합니다.

이러한 방식은 API를 더욱 빠르고 유연하게 개발자 친화적으로 거래 처리를 위한 기능을 만들기 위해 설계되었습니다. 개발자가 단일 API 호출로 다양한 데이터 소스에서 데이터를 CRUD 처리를 구성하는 기능을 구현 할 수 있도록 지원하고 엔지니어에게 기존 운영에 영향을 미치지 않고 API를 추가하거나 폐기할 수 있는 유연성을 부여합니다.

개발자는 업무 기능을 SQL/Batch/OpenAPI/C#/Node.js 등등 선호하는 방식으로 API를 빌드할 수 있으며, transact 모듈 거래 전문 프로토콜은 이러한 API가 예측 가능한 방식으로 작동하도록 보장합니다. 이는 효과적인 API 관리를 위한 핵심 사항입니다.

transact 모듈은 거래를 할 때 최소한의 네트워크 왕복으로 클라이언트에서 원하는 데이터를 응답 받을 수 있도록 하는 업무에 목적을 두고 있습니다. 이 방식은 클라이언트/서버 개발 담당자의 협업 방식에도 영향을 줍니다. (기본적으로 화면 개발자는 서버 개발자가 작성한 API의 요청과 응답 형식에 의존하게 됩니다.)

요청 거래 전문정보​

클라이언트와 서버간에 전송되는 거래 전문 데이터 포맷으로 JSON을 사용하며 성능, 보안, 호환성 등등 다양한 이슈에 대응하기 위해 TSV (Tabluar Separated Values) 정보 데이터를 사용합니다. 다음과 같이 헤더(설명)와 바디(정보)가 하나로 되어있는 단일 메시지 구조를 가지고 있습니다.

명칭역할설명필수여부
global헤더환경, 인증, 식별 정보O
system헤더요청 시스템 정보O
interface헤더거래 통신 정보O
transaction헤더거래 업무 정보O
payLoad본문요청 거래 정보
{
    "accessToken": "",
    "action": "SYN",
    "kind": "BIZ",
    "clientTag": "HANDSTACK|WebClient|ack|D",
    "loadOptions": {
        "encryptionType": "P",
        "encryptionKey": "G",
        "platform": "Win32",
        "dynamic": "Y",
        "authorize": "N",
        "commandType": "D",
        "returnType": "Json",
        "transactionScope": "N",
        "transactionLog": "Y"
    },
    "requestID": "LD00000HDSHMLHML010LD01W76M6JH160600",
    "version": "001",
    "environment": "D",
    "system": {
        "programID": "HDS",
        "version": "1.0.0",
        "routes": [
            {
                "systemID": "HANDSTACK",
                "requestTick": 1700809560524
            }
        ],
        "localeID": "ko-KR",
        "hostName": "localhost:8000",
        "pathName": "/handsup/view/TST/TST010.html"
    },
    "interface": {
        "devicePlatform": "browser",
        "interfaceID": "WEB",
        "sourceIP": "192.168.0.45",
        "sourcePort": 0,
        "sourceMAC": "",
        "connectionType": "4g",
        "timeout": 180000
    },
    "transaction": {
        "globalID": "LD00000HDSHMLHML010LD01S76M6JH160600",
        "businessID": "HML",
        "transactionID": "HML010",
        "functionID": "LD01",
        "commandType": "D",
        "simulationType": "P",
        "terminalGroupID": "undefined|undefined",
        "operatorID": "handstack@handstack.kr",
        "screenID": "HML010",
        "startTraceID": "",
        "dataFormat": "J",
        "compressionYN": "N"
    },
    "payLoad": {
        "property": {},
        "dataMapInterface": "Row|Grid",
        "dataMapCount": [
            1
        ],
        "dataMapSet": [
            [
                {
                    "id": "ApplicationNo",
                    "value": "08dbcde8520ce00cca91a85e00064bf7"
                }
            ]
        ],
        "dataMapSetRaw": []
    }
}

소스) 요청 데이터

global 헤더 환경, 인증, 식별 정보​

필드 ID필드 명설명데이터타입기본값필수
accessToken인증토큰사용자 인증 및 권한 확인을 위한 토큰 정보stringO
action실행의도요청의 실행 의도 정보: SYN(요청/응답), PSH(응답없는 요청), ACK(구독수신 요청)stringSYNO
kind거래의도요청 거래의 성격을 위한 의도 정보: BIZ(업무), DBG(디버깅), URG(긴급), FIN(완료)stringBIZO
clientTag클라이언트 식별 구분 ID시스템ID + 호스트 명 + 프로그램 명 + 환경구분 정보stringO
requestID요청 ID거래 추적을 위한 고유 요청 IDstringO
version전문 버전호환성 유지를 위한 요청 전문 버전string1.0.0O
environment환경구분요청 시스템 환경정보: D(Development), P(Production), T(Test), S(Staging)stringDO

system 헤더 요청 시스템 정보​

필드 ID필드 명설명데이터타입기본값필수
programID프로그램 ID요청 프로그램 식별 IDstringsyn.Config.ApplicationIDO
version시스템 버전요청 시스템 버전stringsyn.Config.SystemVersionO
routes라우트 목록메시지가 거쳐온 시스템 ID, 시간 정보string자동부여
localeID언어권 ID요청/응답에 우선 적용할 언어권 IDstringsyn.Config.Program.LocaleID
hostName호스트 명요청 호스트 식별 정보string자동부여
pathName요청 경로요청 화면 정보string자동부여

interface 헤더 거래 통신 정보​

필드 ID필드 명설명데이터타입기본값필수
devicePlatform단말 플랫폼명거래 요청 단말의 실행 플랫폼 명 (browser, android, ios, node)stringbrowser
interfaceID인터페이스 IDWEB/WIN/SVC등 전송 매체 코드stringsyn.Config.Transaction.MachineTypeID
sourceIP클라이언트 IPIPv4/IPv6 기반 클라이언트 IP 주소string자동부여
sourcePort클라이언트 Port클라이언트 Port 번호string자동부여
sourceMAC클라이언트 MAC구분값이 없는 16진수 클라이언트 MAC 주소string자동부여
connectionType연결구분 ID클라이언트와 서버간의 네트워크 신호를 주고받는 방법 구분string자동부여
timeout제한시간요청후 응답 시간까지 대기 가능한 의도된 제한시간stringsyn.Config.TransactionTimeout

transaction 헤더 거래 업무 정보​

필드 ID필드 명설명데이터타입기본값필수
globalID전역 거래 ID거래 추적을 위한 고유 전역 IDstring자동부여O
businessID업무 ID업무 분류 IDstringO
transactionID거래 ID업무 실행 IDstringO
functionID기능 ID업무 단위 IDstringO
commandType명령구분D: 데이터베이스, F: 함수, B: 배치, A: API 등 명령 구분 IDstringD
simulationType시뮬레이션 ID개발: D, 운영: P, 테스트: T 목적을 표현하는 구분 IDstringsyn.Config.Transaction.SimulationType
terminalGroupID단말그룹 ID클라이언트의 단말 그룹 정보stringsyn.Config.Program.BranchCode
operatorID사용자 ID사용자 식별자 ID 또는 프로그램 명 정보string자동부여
screenID화면 ID거래 요청 화면 ID 정보string자동부여O
startTraceID거래 추적 ID검증 및 결과 확인 목적으로 부여된 거래 추적 IDstring
dataFormat데이터 포맷payLoad 본문 데이터 형식 구분 ID (J: Json, T: Tabluar Separated Values)stringsyn.Config.Transaction.DataFormatO
compressionYN데이터 압축 여부payLoad 본문 데이터 압축 여부 Y/Nstringsyn.Config.Transaction.CompressionYN

payLoad 본문 요청 거래 정보​

필드 ID필드 명설명데이터타입기본값필수
property클라이언트속성키와 값으로 구성된 옵션 정보string
dataMapInterface데이터 구성요청/응답 데이터 구조 정보stringO
dataMapCount데이터 셋 건수요청 데이터 셋들의 건수 정보stringO
dataMapSetJSON 데이터 셋JSON 요청 데이터 목록 정보string
dataMapSetRawTSV 데이터 셋TSV 요청 데이터 목록 정보string

응답 거래 전문정보​

요청에 의한 서버에서 내려 줄 수 있는 응답 정보는 크게 4가지로 분류됩니다.

  • 정확한 응답
  • 의도된 오류
  • 예기치 못한 예외
  • 서버 장애

응답 정보 분류에 따라 표현 할 수 있는 데이터 포맷과 구성이 달라 질 수 있는 부분을 HandStack 에서는 서버 장애가 발생하지 않는 한 어떠한 분류의 응답이든 클라이언트에서 일관된 처리를 보장하기 위해 다음과 같은 응답을 반환합니다.

{
    "system": {
        "programID": "HDS",
        "version": "",
        "routes": [
            {
                "systemID": "HANDSTACK",
                "hostName": "HOSTNAME",
                "environment": "",
                "requestTick": 1700809560524,
                "acceptTick": 1700809560531,
                "responseTick": 1700809560566
            }
        ],
        "localeID": "ko-KR",
        "hostName": "",
        "pathName": ""
    },
    "transaction": {
        "globalID": "LD00000HDSHMLHML010LD01S76M6JH160600",
        "businessID": "HML",
        "transactionID": "HML010",
        "functionID": "LD01",
        "commandType": "D",
        "simulationType": "P",
        "terminalGroupID": "",
        "operatorID": "",
        "screenID": "",
        "startTraceID": "",
        "dataFormat": "J",
        "compressionYN": "N"
    },
    "message": {
        "responseStatus": "N",
        "mainCode": "T200",
        "mainText": "(성공): 서버가 요청을 제대로 처리",
        "additions": []
    },
    "result": {
        "property": null,
        "outputAction": null,
        "responseType": "0",
        "dataSetMeta": [],
        "dataMapCount": [],
        "dataSet": [
            {
                "id": "GridData0",
                "value": [
                    {
                        "CompanyName": "큐씨엔",
                        "JoinAt": null,
                        "ExpiredAt": "2024-11-13",
                        "Options": null,
                        "CreatedMemberNo": "",
                        "CreatedMemberName": null,
                        "CreatedAt": "2023-11-13",
                        "ModifiedMemberNo": null,
                        "ModifiedMemberName": null,
                        "ModifiedAt": null
                    }
                ]
            }
        ]
    },
    "acceptDateTime": "2023-11-24T16:06:00.5313296+09:00",
    "acknowledge": 1,
    "correlationID": "LD00000HDSHMLHML010LD01W76M6JH160600",
    "exceptionText": "",
    "rowsAffected": 0,
    "responseID": "HANDSTACKHOSTNAMED2023112416062400",
    "loadOptions": {},
    "version": "001",
    "environment": "D"
}

소스) 응답 데이터

global 헤더 환경, 인증, 식별 정보​

필드 ID필드 명설명데이터타입기본값필수
acceptDateTime요청수신시간클라이언트 요청이 수신된 시간 정보string자동부여O
acknowledge응답구분응답에 대한 구분 정보 (1: 정상, 0: 오류)string자동부여O
correlationID전역 거래 ID거래 추적을 위한 요청 전역 IDstring자동부여O
exceptionText예외정보요청 처리 중 예외 발생 정보string자동부여O
rowsAffected총 영향 건수요청 처리후 영향을 받은 총 건수 정보string자동부여O
responseID응답 ID거래 추적을 위한 고유 응답 ID (시스템 ID + 호스트 명 + 환경구분 + 응답시간)string자동부여O
loadOptions응답 옵션응답 데이터를 수신하기 위해 필요한 옵션 정보stringO
version전문 버전호환성 유지를 위한 응답 전문 버전string1.0.0O
environment환경구분응답 시스템 환경정보: D(Development), P(Production), T(Test), S(Staging)stringDO

system 헤더 응답 시스템 정보​

필드 ID필드 명설명데이터타입기본값필수
programID프로그램 ID요청 프로그램 식별 IDstringsyn.Config.ApplicationIDO
version시스템 버전요청 시스템 버전stringsyn.Config.SystemVersionO
routes라우트 목록메시지가 거쳐온 시스템 ID, 시간 정보string자동부여
localeID언어권 ID요청/응답에 우선 적용할 언어권 IDstring자동부여
hostName호스트 명응답 호스트 식별 정보string자동부여
pathName요청 경로응답 컨트롤러 정보string자동부여

transaction 헤더 거래 업무 정보​

필드 ID필드 명설명데이터타입기본값필수
globalID전역 거래 ID거래 추적을 위한 고유 전역 IDstringrequest.Transaction.GlobalIDO
businessID업무 ID업무 분류 IDstringrequest.Transaction.BusinessIDO
transactionID거래 ID업무 실행 IDstringrequest.Transaction.TransactionIDO
functionID기능 ID업무 단위 IDstringrequest.Transaction.FunctionIDO
commandType명령구분D: 데이터베이스, F: 함수, B: 배치, A: API 등 명령 구분 IDstringrequest.Transaction.CommandType
simulationType시뮬레이션 ID개발: D, 운영: P, 테스트: T 목적을 표현하는 구분 IDstringrequest.Transaction.SimulationType
terminalGroupID단말그룹 ID클라이언트의 단말 그룹 정보stringrequest.Transaction.TerminalGroupID
operatorID사용자 ID사용자 식별자 ID 또는 프로그램 명 정보stringrequest.Transaction.OperatorID
screenID화면 ID거래 요청 화면 ID 정보stringrequest.Transaction.ScreenIDO
startTraceID거래 추적 ID검증 및 결과 확인 목적으로 부여된 거래 추적 IDstringrequest.Transaction.StartTraceID
dataFormat데이터 포맷payLoad 본문 데이터 형식 구분 ID (J: Json, T: Tabluar Separated Values)stringrequest.Transaction.DataFormatO
compressionYN데이터 압축 여부payLoad 본문 데이터 압축 여부 Y/Nstringrequest.Transaction.CompressionYN

message 헤더 응답 부가 메시지 정보​

필드 ID필드 명설명데이터타입기본값필수
responseStatus응답 상태 ID응답 메시지 부가 정보 (N: Normal, W: Warning, E: Error)stringN
mainCode메시지 코드HandStack 응답 메시지 코드string자동부여O
mainText메시지 설명HandStack 응답 메시지 설명string자동부여O
additions추가 정보Type, Code, Text로 구성된 거래 응답 추가 메시지 정보stringO

result 본문 응답 거래 정보​

필드 ID필드 명설명데이터타입기본값필수
property서버 속성키와 값으로 구성된 옵션 정보string
outputAction응답 실행 정보클라이언트 응답 정보 수신후 실행할 정보string
responseType응답 데이터 분류응답 데이터 포맷 (Json, Scalar, NonQuery, SQLText, SchemeOnly, CodeHelp, Xml, DynamicJson) 정보string자동부여O
dataSetMeta응답 데이터 타입TSV 응답 데이터 타입 목록 정보string자동부여
dataMapCount데이터 셋 건수응답 데이터 셋들의 건수 정보string자동부여O
dataMapSetJSON 데이터 셋JSON 응답 데이터 목록 정보string자동부여
dataMapSetRawTSV 데이터 셋TSV 요청 데이터 목록 정보string자동부여