고정 헤더 영역
상세 컨텐츠
본문
인터페이스설계서와 프로그램명세서는 개발자가 작성해야 하는 산출물 중 가장 중요하다고 할 수 있습니다. 물론 이 문서를 분석/설계자가 기본적인 작성을 할 수 있으나, 최종 정확한 내용의 정의는 실제 개발한 내역을 바탕으로 상세 내용이 수정되어야 합니다. 그런 의미에서 개발자가 작성한다고 보는 것이 더 타당할 것입니다. 오늘은 이 기종 시스템 또는 다른 솔루션 간의 데이터 교환 및 처리를 위한 여러가지 방식들에 대한 작성법에 대해 알아보도록 하겠습니다.
개요
인터페이스 설계서는 이기종 시스템이나 솔루션 간의 데이터 교환 및 처리를 위한 목적으로 각 시스템의 교환 데이터의 업무, 송수신 주체, 제약사항, 화면 그리고 처리 로직을 설명한 문서입니다. 인터페이스의 종류에는 인터페이스 정의서와 인터페이스 설계서가 있습니다.
인터페이스 정의서 작성하기
인터페이스 정의서는 일반적으로 서버 개발자가 다른 개발자들에게 전달하기 위해 API 명세와 기능을 명확하게 정의하는 문서입니다. 이 문서는 다른 팀원들이 이를 이해하고 활용할 수 있도록 도와주는 문서라고 생각하시면 됩니다.
다음은 조직도 연동 관련 인터페이스 정의서를 작성한 예시입니다.
먼저, 조직도 연동의 구조를 이미지화하여 표시합니다.
구조
인사서버와 API 연동을 통해 그룹웨어서버로 조직도를 연동합니다.
파일
조직도 연계를 위한 파일들의 위치와 내용을 설명합니다.
| 파일 위치 | 설명 |
| /xxxx/WEB-INF/classes/~~/*.class | API를 작동하기 위한 class |
| /xxxx/WEB-INF/classes/~~/*.java | Class 의 java 파일 |
| /xxxx/WEB-INF/classes/~~/compile.sh | Class 파일을 컴파일 하기 위한 쉘 |
| /xxxx/linkage/~~/log4j.* | Class 에서 만들어지는 로그파일 설정 |
| /xxxx/linkage/~~/db*.jsp | 디비 정보 입력파일 |
| /xxxx/linkage/~~/log*.jsp | API 로그파일 정의 |
| /xxxx/linkage/~~/*.jsp | API 호출 jsp |
설정
다음은 db, log파일의 설정을 위한 위치파일을 설명합니다.
| 구분 | 설명 |
| db*.jsp | ## happy.*의 위치를 넣어준다. |
| *.load(new FileInputStream("/home/***/happy/happy.*")); | |
| log*.jsp |
## 로그파일의 위치를 넣어준다. |
| String logfilename = "/home/***/xxxx/ ~~/"+filename+"_jsp.log"; | |
| log4j.* |
## 로그파일의 위치를 넣어준다. |
| log4j.*.*.file=/home/***/xxxx/~~/org*.log | |
| *.java |
## 로그파일의 위치를 넣어준다. |
| *ertyConfigurator.configure("/home/xxxx/~~/log4j.*"); | |
| ## 이후 compile.sh를 통하여 컴파일 진행 | |
| ## 컴파일시 warning 는 무시 |
API 정의
다음은 조직도 정보인 사용자, 부서, 직위, 직급 등의 내용과 정보변경 등을 확인합니다.
| 사용자 | ## 파일 |
| /~~/get*.jsp | |
| ## 파라메터 | |
| SABUNCODE=<사번> | |
| ## 출력 내용 | |
| ~~ 생략 | |
| 부서 | ## 파일 |
| /~~/get*.jsp | |
| ## 파라메터 | |
| BUSOCODE=<부서코드> | |
| ## 출력 내용 | |
| ~~ 생략 | |
| 직위 | ## 파일 |
| /~~/get*.jsp | |
| ## 파라메터 | |
| JIKWINAME=<직위명> 한글인 경우 URL 인코딩 필요 | |
| JIKWICODE=<직위코드> | |
| ## 출력 내용 | |
| ~ ~생략 |
로그
로그파일을 세팅하는 방법을 작성합니다.
| log*.jsp | ## jsp 에서 나오는 로그 위치 |
| String logfilename = "/home/~~/"+filename+"_*.log"; | |
| log4j.* | ## java에서 나오는 로그 위치 |
| log4j.*.*.file=/home/~~/org*.log |
인터페이스 설계서 작성하기
세션값 조회
그룹웨어의 사원번호와 요청자의 클라이언트IP를 전달하여 그룹웨어의 값을 조회하는 API를 설명하고 송수신 형태를 작성하고, 화면예시도 작성합니다. (본 글에서는 화면예시 제외함)
| 시스템 명 | 그룹웨어 | ||||||
| API 명 | 세션값 조회 | ||||||
| API 주소 | protocol://host(domain):port/custom/sso/1234.jsp [ex] http://100.101.258.332/custom/sso/1234 |
||||||
| API 설명 | 그룹웨어의 사원번호와 요청자의 ClientIP를 전달하여 그룹웨어의 세션값을 조회 | ||||||
| 제약사항 | 요청하는 서버 IP가 허가된 IP로 등록되어있어야 요청 가능. 호출하는 시스템담당자가 그룹웨어 담당자에게 서버IP 전달. |
||||||
| 운영서버URL | https://www.happy.co.kr 예시임 | ||||||
| Request Type | GET / POST | ||||||
| Response Type | JSON | ||||||
| Request Parameters | Key | Type | Description | ||||
| SAWONCode | String | 사용자의 사원번호 | |||||
| clientIP | String | 사용자의 클라이언트 IP | |||||
| Response Result | Key | Type | Description | ||||
| key | String | 조회 실패시 공백 반환, 성공시 세션값 반환 | |||||
| result | String | [FAIL / SUCCESS]의 값 반환 조회 실패시 FAIL 반환, 성공시 SUCCESS 반환 |
|||||
| message | String | 조회 실패시 1. 허가된 서버가 아닙니다. 2. 사용자 정보를 찾을 수 없습니다 3. 프로세스 처리 중 실패하였습니다 조회 성공시 1. 성공 |
|||||
다음은 수신 응답 샘플과 필드 설명내용입니다.
| Response Sample | 필드 설명 | ||||||
| 호출서버IP가 등록되어 있지 않을경우 |  |
||||||
| 요청한 사번이 그룹웨어에 없을경우 |  |
||||||
마치며
오늘은 설계 단계 산출물 중 인터페이서 정의서 및 설계서 작성법에 대해 알아보왔습니다.
인터페이스 정의서는 일반적으로 서버 개발자가 다른 개발자들에게 전달하기 위해 API 명세와 기능을 명확하게 정의하는 문서이며, 인터페이스 설계서는 이기종 시스템이나 솔루션 간의 데이터 교환 및 처리를 위한 문서입니다. 이 문서를 명확하게 작성함으로써 개발에 대한 혼란과 문제 그리고, 개발 협의를 현저히 줄일수 있어 개발 시간을 단축할 수 있습니다.
다음편에서는 설계 산출물 중 ERD 및 테이블 정의서에 대해 살펴보도록 하겠습니다.
프로젝트에 대해 다른 사항이 궁금하시면 아래 링크를 클릭하세요
(1편) 프로젝트: 기술협상서 작성하기
(2편) 프로젝트: 사업수행계획서, WBS 작성하기
