코드 구조 분석을 진행하기 앞서, FreeRTOS에는 중요한 코딩룰을 먼저 알아보자.

1-1. 변수명

FreeRTOS에서는 변수명 결정시, 타입에 따라 아래와 같은 접두어를 사용한다

• c : char Type
• s : int16_t Type (short)
• i : int32_t Type (int)
• x : BaseType_t Type, 주로 구조체나 인스턴스 핸들 등 일반적인 타입을 제외하면 대부분 x
• u : unsigned
• p : pointer

1-2. 함수명

• v : void, 반환값이 없는 함수를 의미
• x : 변수명의 접두어 x와 같은 의미, BaseType_t를 반환하는 함수
• pv : void* 타입을 반환하는 함수
• prv : private 함수, 대표적으로 아무런 task도 실행되지 않을 때 실행되는 idle task가 호출하는 callback 함수인 hook가 이 접두어를 사용하고 있음

2. Handle

내부적으로 생성된 객체를 관리하고 식별하기 위한 포인터 타입, 보통 Task, Queue, Semaphore, Timer 등과 같은 RTOS 객체를 가리키는 참조(포인터) 형태의 자료 구조.

• TaskHandle_t : Task를 식별하는 데 사용되는 핸들
• QueueHandle_t : Queue를 식별하는 데 사용되는 핸들
• SemaphoreHandle_t : Semaphore(Mutex 등)를 식별하는 데 사용되는 핸들
• TimerHandle_t : 소프트웨어 타이머를 식별하는 데 사용되는 핸들

3. Task API

FreeRTOS에서 제공해주는 Task 관련 API가 있다. 대표적으로 몇가지 알아보자면,

3-1. xTaskCreate()

BaseType_t xTaskCreate( TaskFunction_t pvTaskCode,
                        const char * const pcName,
                        unsigned short usStackDepth,
                        void *pvParameters,
                        UBaseType_t uxPriority,
                        TaskHandle_t *pxCreatedTask)

• pvTaskCode : task의 기능이 선언된 함수의 함수 포인터
• pcName : 디버깅 용도로 사용하는 문자열이며, task의 이름을 말함
• usStackDepth : task마다 할당되는 stack 메모리를 말하며, 단위는 WORD. 일반적으로 사용하는 ARM Cortex-M 보드에서는 1WORD == 4Byte
• pvParameters : task 함수로 전달할 매개변수, 없으면 NULL 사용. 전달할 매개변수를 (void*) 타입으로 캐스팅한 뒤 여기다가 넣어주면 task 함수에서 사용할 수 있음
• uxPriority :
• *pxCreatedTask : task를 제어하기 위한 TaskHandle_t 타입 핸들, Task의 우선순위를 바꾸거나, task를 멈추거나 등 task에 대한 설정은 모두 이 핸들을 통해 이루어짐.

(예시)

xTaskCreate( prvQueueReceiveTask,                // Task 함수, 실제 실행될 로직
             "RX",                                // 디버깅 시 확인할 수 있는 이름, 커널 내부에서 직접 쓰이지는 않음
             configMINIMAL_STACK_SIZE,            // 스택 크기
             NULL,                                // 입력 파라미터, Task가 필요로 한다면 다른 파라미터를 넣어 사용할 수 있음
             mainQUEUE_RECEIVE_TASK_PROIRITY,    // 우선순위, 어느 Task를 더 자주/빨리 실행할지 결정, 우선순위가 높을수록 CPU 점유 기회가 많아짐
             NULL );                            // Null을 넘기면 Task 핸들을 별도로 받지 않음, Task 핸들이 필요하면 변수로 받아서 vTaskDelete()등에 활용 가능

3-2. vTaskDelay()

void vTaskDelay( TickType_t xTicksToDelay );

• Task의 상태를 Running에서 Blocked(waiting)으로 변경하는 함수
• 설정된 시간 xTicksToDelay 동안 Task는 blocked Task가 되며, 다음 우선순위를 가진 task가 실행됨
• 확정성 및 이식성 좋은 코드를 만들기 위해서 tick 단위 시간을 사용하는 것 보다 pdMS_TO_TICKS() 매크로를 사용해서 ms 단위를 tick으로 변환해서 사용하는 것이 좋음

3-3. vTaskDelayUntil()

• vTaskDelay()와 똑같은 기능을 수행하지만, vTaskDelay()는 호출 시점부터 지정된 시간만큼 blocked 되는 반면,
• vTaskDelayUntile()은 호출 시점과 관계없이 목표 절대 시간 주기에 맞춰 blocked 됨

3-4. vTaskSuspend(), vTaskResume()

• Delay 함수들은 Task를 일정 시간동안 blocked state로 만들지만, suspend 함수는 task를 기약없이 blocked state로 만듬 (resume 함수를 사용할 때 까지)
• Task의 우선순위를 바꿀때, Task를 일단 blocked state로 만들기 위해 사용하며, 인자값으로 task의 handle이 들어감

3-5. vTaskPrioritySet()

• Task의 우선순위를 바꿀때 사용하는 API

4. Posix_gcc Demo : main_blinky()

드디어 main_blinky()를 분석해보자.

main_blinky()는 Posix_gcc Demo의 main() 함수에 정의된 mainSELECTTED_APPLICATION = 0 일 때, 호출되는 함수이다.

4-1. Signal 처리 함수 호출

main 함수가 호출됨가 동시에, 먼저 시그널 처리 함수를 등록한다.

signal( SIGINT, handle_sight);

• signal 함수는 시그널 처리 함수를 등록하는 함수로, SIGINT는 일반적으로 프로그램 실행 중, 키보드로부터 인터럽트가 들어왔을 때 발생하는 시그널

• 프로그램 실행 중, 사용자가 Ctrl+C를 눌러 종료 신호를 보냈을 때 바로 종료되는 대신 handlo_sight 함수에서 필요한 동작(자원 정리 및 로그 출력 등)을 수행하도록 설정해주는 코드

4-2. Mutex(뮤텍스) 생성

그 다음으로는 콘솔(또는 표준 입출력) 사용을 위한 뮤텍스(Mutex)를 생성하는 함수 console_init()을 호출한다.

console_init();

해당 함수에서는 FreeRTOS에서 제공하는 xSemaphtoreCreateMutex() 또는 xSemaphtoreCreateMutexStatic() 함수를 사용해, 멀티태스킹 환경에서 여러 Task가 동시에 콘솔 입출력을 수행할 때 충돌이 일어나지 않도록 보호한다.

void console_init(void)
{
    #if (configSUPPORT_STATIC_ALLOCATION == 1)
    {
        xStdioMutex = xSemaphoreCreateMutexStatic( &xStdioMutexBuffer );
    }
    #else
    {
        xStdioMutex = xSemaphoreCreateMutex();
    }
    #endif
}

4-3. main_blinky()

mainSELECTED_APPLICATION = 0이라는 가정하에, 이제 main_blinky() 함수로 진입한다. 해당 함수 안에는 Timer 및 Task, Scheduler 등이 선언되어, main 함수에서 실질적인 동작을 수행한다.

4-3-1. 타이머 동작 주기 설정

먼저, 변수 타이머 동작 주기 변수 xTimerPeriod는 다음과 같이 선언된다.

const TickType_t xTimerPeriod = mainTIMER_SEND_FREQUENCY_MS;

이때, mainTIMER_SEND_FREQUENCY_MS는

#define mainTIMER_SEND_FREQUENCY_MS        pdMS_TO_TICKS(2000UL)

로 정의된다.

즉, 매크로 pdMS_TO_TICKS를 통해 1 Tick을 2000ms으로 정의하고 (pdMS_TO_TICKS(2000UL)),

타이머 동작 주기를 1 Tick, 즉 2000ms로 설정해주는 과정이다.

4-3-2. Queue 생성

xQueue = xQueueCreate( mainQUEUE_LENGTH, sizeof( uint32_t ));

xQueueCreate 함수로, Queue를 생성해주는 과정이다. 생성된 Queue인 xQueue는 길이가 mainQUEUE_LENGTH이고, 각 element의 크기는 32bit 정수 크기인 형태로 생성된다(sizeof( uint32_t)))

4-3-3. Task 생성

해당 데모에서는 2개의 Task를 생성한다. Task를 생성하기 위해선, xTaskCreate API를 사용한다.

하나는 Queue로부터 데이터를 받아 메시지를 생성해주며,

xTaskCreate( prvQueueReceiveTask,                // Task 함수, 실제 실행될 로직
             "RX",                                // 디버깅 시 확인할 수 있는 이름, 커널 내부에서 직접 쓰이지는 않음
             configMINIMAL_STACK_SIZE,            // 스택 크기
             NULL,                                // 입력 파라미터, Task가 필요로 한다면 다른 파라미터를 넣어 사용할 수 있음
             mainQUEUE_RECEIVE_TASK_PROIRITY,    // 우선순위, 어느 Task를 더 자주/빨리 실행할지 결정, 우선순위가 높을수록 CPU 점유 기회가 많아짐
             NULL );                            // Null을 넘기면 Task 핸들을 별도로 받지 않음, Task 핸들이 필요하면 변수로 받아서 vTaskDelete()등에 활용 가능

그리고, 다른 하나는 Tick을 Count한 값을 Queue에 값을 전송하는 Task이다.

xTaskCreate( prvQueueSendTask,
             "TX",
             configMINIMAL_STACK_SIZE,
             NULL,
             mainQUEUE_SEND_TASK_PRIORITY,
             NULL );

4-3-4. 소프트웨어 타이머 생성

그리고 그 다음으로 소프트웨어 타이머를 생성해준다.

xTimer = xTimerCreate( "Timer",                            //타이머 이름, 디버깅용
                        xTimerPeriod,                    //타이머 주기
                        pdTRUE,                            //pdTRUE면, 타이머가 만료될 떄마다 자동으로 다시 시작, pdFALSE면 한번 만료된 후 자동으로 멈춤
                        NULL,                            //타이머 ID, NULL이므로 별도로 ID를 저장하진 않음. 여러 타이머를 관리할 때 식별이 필요하다면 다른 값을 넣을 수 있음
                        prevQueueSendTimerCallback    );    //콜백 함수 : prvQueueSendTimerCallback이 타이머가 만료될 때마다 실행하는 함수를 가리킴

4-3-5. 타이머 시작

타이머가 정상적으로 생성된 경우, xTimerStart() 함수를 통해 타이머 시작

if( xTimer!=NULL )
{
    xTimerStart( xTimer, 0 );
}

4-3-6. 스케줄러 시작

vTaskStartScheduler();

모든 Task와 타이머가 생성된 뒤, RTOS 스케줄러를 시작하면, 등록된 Task들이 우선순위와 준비 상태(Ready State)에 따라 CPU를 할당받아 실행된다.

등록된 소프트웨어 타이머도 FreeRTOS 타이머 서비스(Task)에 주기적으로 콜백이 호출되고, 스케줄러가 시작된 후에는 main() 함수로는 다시 돌아오지 않는 것이 일반적이다.

*참고 : RTOS 스케줄러가 시작되면, 내부적으로 무한 반복 구조로 동작한다. 따라서, 일반적인 C프로그램처럼 While(1) 루프를 직접쓰지 않아도, RTOS 스케줄러가 각 Task를 무기한으로 스케줄링하고 실행해준다.

5. 마치며

가장 기초적인 예제를 통해, FreeRTOS에서 Task를 생성하는 방법, API를 사용하는 방법 등을 알아봤다. 다음 글에는 Posix_gcc에서 두번째 실행 함수 main_full() 함수를 분석하겠다.

FreeRTOS 실험 및 실제 임베디드 하드웨어로 포팅하기 위한 FreeRTOS 애플리케이션을 개발할 수 있는 환경을 제공

하지만, Linux 포트를 사용하는 FreeRTOS 애플리케이션은 실시간 동작을 보이진 않음

2. 환경설정

2-1. GCC ARM 툴체인 설치

ARM Cortex-M 시리즈 프로세서를 대상으로 하는 바이너리를 빌드할 있는 컴파일러 설치

sudo apt install gcc-arm-none-eabi gdb-multiarch

3. FreeRTOS 소스 코드

3.1 FreeRTOS 소스 코드 다운로드

FreeRTOS의 최신 소스 코드를 GitHub에서 클론

git clone https://github.com/FreeRTOS/FreeRTOS.git

설치가 완료되면, 해당 디렉토리로 이동

cd FreeRTOS

*그리고 Submodule을 설치해줘야한다. (내가 못찼은건지 모르겠지만, 공식 문서에서 찾은게 아닌, Stack Overflow 열심히 해매면서 찾아냈다..)

git submodule update --init --recursive

3.2 소스 코드 구성

• Linux용 RTOS Port Layer(POSIX) 위치

  FreeRTOS/Source/portable/ThirdParty/GCC/Posix

• Demo Project (1) : 커널 전용 데모

  FreeRTOS/Demo/POSIX_GCC

• Demo Project (2) : 네트워킹 데모

  FreeRTOS-Plus/Demo/FreeRTOS_Plus_TCP_Echo_Posix

3-3. Posix/Linux 시뮬레이터 소개

• 해당 프로젝트는 Linux(POSIX) 포트를 사용하여 FreeRTOS 커널 기능을 보여주는 프로젝트

간단한 *Blinky 스타일 데모(BLINKY_DEMO), 또는 보다 *포괄적인 스타일 데모(FULL_DEMO) 상수를 설정하여(mainSELECTED_APPLICATION), main.c 가장 상단에 정의되어 있음

(FULL_DEMO로 설정된 경우)

3-3-1. Bliny Demo

• mainSELECTED_APPLICATION이 BLINKY_DEMO로 설정되어 있을 경우,

• main() 함수는 main_blinky() 함수를 호출함 (from main_blinky.c)

• main_blinky()는 2개의 Task (software timer 및 queue로 구성된)를 포함하고 있으며,

  

• 하나의 Task(송신 Task)는 200ms마다 queue를 통해 값 100을 다른 Task로 반복적으로 전송하며, (예시)

• timer는 2000ms마다 같은 queue에 값 200을 전송함 (예시)

• 그리고 수신 Task는 queue에서 두 값 중 하나를 받을때마다 메시지를 출력함

3-3-2. Full Demo

• mainSELECTED_APPLICATION이 FULL_DEMO로 설정되어 있을 경우,

• main() 함수는 main_full() 함수를 호출함 (from main.full.c)

• main_full()은 하나의 the standard demo tasks들로 구성되어 있으며, 해당 Task는 특정한 기능을 수행하지는 않고, RTOS 포트의 테스트 및 FreeRTOS API 사용 방법을 보여주는 역할을 함

• 전체 데모에는 check Task가 포함되어 있으며, 이 Task는 10초마다 실행되며, 가장 높은 우선수위를 가져 항상 처리 시간을 확보할 수 있도록 보장됨.(해당 Task의 주요 기능은 모든 표준 데모 태스크가 여전히 정상적으로 동작하고 있는지 확인하는 역할을 함)

• Check Task는 실행될 때마다 상태 문자열을 콘솔에 출력하며, 만약 모든 표준 데모 태스크가 오류 없이 실행 중이라면, 문자열에는 "OK"와 현재 틱 카운트가 포함됨 (예시)

• 반면, 오류가 감지되면 해당 문자열에는 오류를 보고한 Task를 나타내는 메시지가 포함됨 (예시)

4. FreeRTOS 데모 프로젝트 빌드

Posix/Linux 시뮬레이터 데모를 위해, 경로 이동 (현 예제에서는 커널 전용 데모를 빌드하고자 하여, 3.2에서 기술한 Demo Project (1) : 커널 전용 데모 의 경로에서 진행)

cd FreeRTOS/Demo/Posix_GCC

make 명령어로 Posix_GCC 데모 프로젝트 빌드

make

빌드가 성공적으로 완료되면, build 디렉토리가 생성되며, 하위에 posix_demo 파일이 생성됨

5. (Linux) 데모 프로그램 실행

posix_demo 파일 실행

./posix_demo

*[실행화면]

사용자들은 원하는 데이터를 추출하기 위하여 select 구문을 사용하며, select 구문은 데이터를 질의하는 구문이무로 DQL 문이라고도 함

SQL 구문 작성 지침

• 키워드 예약어 등에 대한 대소문자 구분이 없음
• 여러 라인에 걸쳐서 작성 가능함
• 키워드는 줄여서 쓰거나 나눠서 쓰면 안됨
• 절과 절은 나뉘어 사용
• 적절한 들여 쓰기는 가독성을 향상시킴
• 세미콜론 (;) 을 사용하여 문장의 끝을 표시하도록 함

기본 데이터 조회 명령어

select * from employees;

비교 연산자

select * from employees
where id='an';

논리 연산자

select * from employees
where salary>=600 and salary<=1000;

널 데이터

• 비교 판단이 불가능한 정의할 수 없는 어떠한 값
• 연산 결과 값은 모두 Null
• 비교시, 연산자 대신 is null로 비교 가능
• 연결 연산자와 합쳐지는 경우에는 흡수

  select * from employees
  where salary is null;

Between 연산자

Between 하한값 and 상한값 이 때, 하한값과 상한값은 모두 구하고자 하는 범위에 포함

select * from employees
where salary between 120 and 500;

in 연산자

select * from employees
where manage in ("kim9", "yusin");

like 연산자

• % : 0개 이상의 문자열을 의미

• _ : 반드시 1개의 문자를 의미

• 첫 글자가 [선]인 회원 : select * from employees where name like "선%";

• 이름 중에 [연]이라는 글자가 있는 회원 : select * from employees where name like "%연%";

• 이름의 2번째 글자가 [리] 인 회원 : select * from employees where name like "_리";

• 이름 중에 [성]이 들어 있는 회원 : select * from employees where name like "%선%";

부정어 사용하기

• where id not in ('kim9', 'yusin');
• where marriage not in('이혼');
• where salary not between 220 and 230;
• where name not like '김%';
• where salary is not null;
• where manager is not null;

연산자의 복합적 사용

여러 키워드를 복합적으로 사용 가능

ex) 성씨가 "김"씨 이거나 "여자"인 회원들을 출력하되, 이름에 대하여 내림차순 정렬

select * 
from employees 
where name like "김%" or gender="여자"
order by name desc;

• 트랜잭션은 데이터 처리에 있어 하나의 논리적 단위.
• 트랜잭션이 필요한 이유는 데이터의 무결성을 유지하고, 일관성 있게 안정적으로 데이터를 유지하기 위함

트랜잭션의 개념

구매 : 강감찬이 사과 10개와 배 20개를 구매 Update : 상품의 재고 수량이 감소 Insert : 주문 테이블에 주문 내역이 추가 Update : 회원의 마일리지 포인트 적립

위 4건의 업무를 논리적으로 보았을 때 하나의 묶음 단위로 처리가 되어야 하며, 이러한 논리적은 묶음을 트랜잭션이라고 함

트랜잭션 제어어

• 데이터 조작어(DML)는 해당 작업이 실행 됨과 동시에 트랜잭션이 시작됨
• 이러한 작업이 영구적으로 저장이 되려면 commit 명령어를
• 취소하기 위해선 rollback 명령어를 사용
• commit과 rollback 명령어에 의해 트랜잭션은 종료됨

커밋(Commit)

이전에 수행했던 모든 작업들을 영구적으로 저장하겠다고 데이터베이스에 알려주는 명령어로, commit 명령어를 사용하면 해당 지점까지 하나의 트랜잭션이 종료됨

<----- 첫 번째 트랜잭션 -----> <----- 두 번째 트랜잭션 -----> Insert > Update > Delete > Insert > Update > Delete (출근) --------------- (Commit) --------------- (Commit)

출근과 동시에 첫 번째 트랜잭션이 시작되며, Commit 과 동시에 첫번째 트랜잭션이 종료됨, 이후 두 번째 Insert문이 시작되는 지점에서 두 번째 트랜잭션이 시작됨

롤백(Rollback)

작업을 수행하다가 사용자의 실수로 인한 명령어 취소 또는 어떠한 문제가 발생하였을 때 발생했던 모든 변경 사항들을 취소하고자 할 때 사용하는 명령어

<----- 첫 번째 트랜잭션 -----> <----- 두 번째 트랜잭션 -----> (1)--------------------(2)--(3)--------------------(4) Insert > Update > Delete > Insert > Update > Delete (출근) --------------- (Commit) --------------- (rollback)

(3) 지점에서 두 번째 트랜잭션이 시작되었을 때, (4) 지점에서 트랜잭션이 완료되었으나 rollback 이 발생하게됨. 이로 인해 두 번째 트랜잭션이 수행되기 전인 (2) 지점으로 원상 복귀함

저장점(Savepoint)

저장점은 큰 트랜잭션을 작게 분할하는 기법으로, 중간 중간에 저장된 저장점까지 rollback을 수행할 수 있음

(명령어)

savepoint 레이블_이름
rollback to 레이블_이름

------(1)------------------(2)-----------------(3)-------(4)

insert >> update >> delete >> insert >> update >> delete

----commit-----------savepoint1---------savepoint2---commit

(4) 지점에서 rollback 할 경우, (1) 지점으로 (4) 지점에서 rollback to savepoint1 할 경우, (2) 지점으로 (4) 지점에서 rollback to savepoint2 할 경우, (3) 지점으로

원상 복귀 되어짐

실습

CTAS 기법을 통해 집합 연산자 파트에서 좀 더 세부적으로 나눔

create table myemp as
select id, name, salary, marriage, gender from employees;

성별이 여자인 사람의 급여를 1000으로 설정

update myemp1 set salary=1000 where gender='여자';
commit;

select * from myemp1;

savepoint 실습 이전 테이블을 삭제하고 테이블 다시 생성

create table myemp2 as
select id, name, salary, marriage, gender from employees;

select * from myemp2;

최초의 상태를 savepoint point01로 지정, 그 후 성별이 여자인 회원의 급여를 1000으로 수정

savepoint point01;
update myemp2 set salary=1000 where gender='여자';
select * from myemp2;

현재의 상태를 savepoint point02로 지정, 성별이 남자인 회원을 모두 삭제

savepoint point02;
delete from myemp2 where gender='남자';
select * from myemp2;

rollback to 문구를 사용해 savepoint point02 지점으로 이동

rollback to point02;
select * from myemp2;

savepoint point01 지점으로 이동

rollback to point01;
select * from myemp2;

테이블의 행(row)에 대하여 추가/수정/삭제 등을 수행하기 위한 언어

• Transaction 및 undo 데이터에 대한 지식이 필요함

행(row) 추가하기

(명령어)

insert into 테이블이름(컬럼01, 컬럼02, …)
values(값01, 값02, …)

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('yusin', '김유신', 'abc123', '남자', '1990/12/25', '결혼', 220, '용산', null);

다시, employees 테이블 생성

CREATE TABLE employees ( 
    id VARCHAR(20) PRIMARY KEY, 
    name VARCHAR(30) NOT NULL, 
    password VARCHAR(20) NOT NULL, 
    gender VARCHAR(10), 
    birth DATE, 
    marriage VARCHAR(30), 
    salary DECIMAL(10, 2) DEFAULT 100.00, 
    address VARCHAR(50), 
    manager VARCHAR(50) 
);

몇 건의 데이터 추가

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('yusin', '김유신', 'abc123', '남자', '1990/12/25', '결혼', 220, '용산', null);

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('lee', '이순신', 'abc123', '남자', '1990/12/25', '이혼', 220, '용산', null);

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('choi', '최영', 'abc123', '남자', '1990/12/25', '결혼', 155, '용산', 'yusin');

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('kang', '강감찬', 'abc123', '남자', '1990/12/25', '결혼', null, '용산', 'yusin');

(결과)

컬럼 이름을 명시하는 경우 컬럼의 갯수와 데이터의 타입을 반드시 맞춰줘야함

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('yoon', '윤봉길', 'abc123', '남자', '1990/12/25', '미혼', 230, '용산', 'yusin');

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('kim9', '김구', 'abc123', '남자', '1990/12/25', '이혼', 280, '강남', null);

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('general', '김좌진', 'abc123', '남자', '1990/12/25', '결혼', 550, '마포', 'kim9');

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('an', '안중근', 'abc123', '남자', '1990/12/25', '결혼', 155, '용산', 'kim9');

입력이 필요 없는 컬럼을 명시하지 않는 경우 굳이 명시할 필요가 없는 컬럼은 insert 구문에 작성할 필요없음, 급여가 책정되지 않은 직원의 경우 기본값 100으로 입력됨

Insert into employees(id, name, password, gender, birth, marriage, address, manager)
values('nongae', '논개', 'abc1234', '여자', '1990/12/25', '미혼', '강남', 'soon');

연산자 살펴 보기

비교 연산자

논리 연산자

예시

select * from employees where name='강감찬' or name='논개';

행 수정하기

Update 구문은 이미 저장이 되어 있는 데이터 값을 변경하고자 하는 경우 사용하는 문장

(명령어)

update 테이블_이름
set 컬럼1=값1, 컬럼2=값2, …, 컬럼n = 값n
Where 조건식;

Ex) 모든 직원들의 월급 100으로 설정

update employees 
set salary=100;

Ex) 모든 회원들의 생일을 오늘로

Ex) 모든 회원들의 급여를 500으로, 비번은 ‘abcd1234’로 변경

Ex) 안중근의 급여를 400으로 조정

다시 뒤로 (Rollback)

(명령어)

rollback;

Ex) 모든 직원들의 급여 10% 인상

in 연산자

아이디가 kim9 이거나 lee이거나 kang 인 항목을 찾아보는 문구?

그런데 in을 사용한다면? (명령어) in (set)

or 연산자 대신에 간략히 표현할 목적으로 만든 키워드 or 연산자의 조합으로 셋트 목록 중의 하나와 일치하는 모두를 의미함

select * from employees where id in ('kim9', 'lee', 'kang');

Ex) in 키워드를 사용해 관리자가 ‘김유신’이나 ‘김구’인 회원들의 급여를 555로 변경

update employees set salary=555 where manager in ('yusin','kim9');

행 삭제하기

delete 문법을 사용함

delete from 테이블_이름 where 조건식;

주의) column 삭제는 불가능하며, 문자와 날짜는 ''(외따옴표)로 둘러싸야함

(예시)

delete from employees;
select * from employees;

"안중근" 회원에 대한 정보 삭제

delete from employees where id='an';
select * from employees;

관리자가 "김유신"인 회원 이름 삭제

delete from employees where manager='yusin';
select * from employees;

관리자가 "soon"이고 급여가 220 이상인 회원 삭제

delete from employees where manager='soon' and salary>=220;
select * from employees;

주소가 '서대문'과 '강남'을 제외한 다른 지역에 거주하는 회원을 삭제

delete from employees where address not in ('서대문', '강남');
select * from employees;

행을 row 또는 record라 부르며, 열을 column 또는 field라 부름

테이블 명세

테이블의 컬럼 이름이나 개수, 데이터의 타입, 기본값, 특이점 등을 명시 해놓은 정보

컬럼의 자료 유형

• number: 숫자형 데이터로 정수 및 실수 사용이 가능함
• varchar2: 가변 길이 문자열 타입으로, 최대 4000 바이트까지 가능
• date: 날짜 데이터 타입으로, 시스템 설정에 따라 출력 형태가 다름

예시

• id의 타입을 길이가 20인 문자열을 사용할 경우

  id varchar2(20)

• salary의 기본값을 100으로 설정할 경우

  salary number default 100

• 필수 사항일 경우

  name varchar(30) not null

기본 키(Primary Key)

기본 키는 각각의 행/레코드를 구별하기 위한 컬럼/필드로, not null이며 다른 행과 중복되어서는 안됨(unique)

• 컬럼 id는 기본키이므로, 다른 컬럼과 중복되어선 안되며 필수적으로 입력되어야함

  id varchar2(20) primary key

데이터베이스 생성

CREATE DATABASE mydatabase;

데이터베이스 실행

USE mydatabase;

테이블 생성 구문

Create table 테이블_이름(
    컬럼_이름 데이터_타입 [not null] [default 기본값] [primary key],
    컬럼_이름 데이터_타입 [not null] [default 기본값]
    …
);

예시

CREATE TABLE employees ( 
    id VARCHAR(20) PRIMARY KEY, 
    name VARCHAR(30) NOT NULL, 
    password VARCHAR(20) NOT NULL, 
    gender VARCHAR(10), 
    birth DATE, 
    marriage VARCHAR(30), 
    salary DECIMAL(10, 2) DEFAULT 100.00, 
    address VARCHAR(50), 
    manager VARCHAR(50) 
);

데이터 추가하기

insert into 테이블이름(컬럼01, 컬럼02, …)
values(값01, 값02, …);

예시

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('yusin', '김유신', 'abc123', '남자', '1990/12/25', '결혼', 220, '용산', null);

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('choi', '최영', 'abc123', '남자', '1990/12/25', '결혼', 220, '용산', 'yusin');

Insert into employees(id, name, password, gender, birth, marriage, salary, address, manager)
values('kang', '강감찬', 'abc123', '남자', '1990/12/25', '결혼', 220, '용산', 'yusin');

테이블의 모든 행 정보 출력하기

select * from 테이블이름;

예시

select * from employees;

테이블 정보 확인

• 테이블의 구조 확인

  desc 테이블명;

테이블 구조 변경

컬럼 추가하기

alter table 테이블_이름 add (컬럼_이름 데이터_타입);

예시

alter table employees add hphone varchar(15);

![](https://velog.velcdn.com/images/dev_junseok_22/post/90f01681-186e-41b9-8648-7de82859ff3a/image.png)


alter table employees add (age int default 0);

![](https://velog.velcdn.com/images/dev_junseok_22/post/6f83c0e3-8e32-4b03-9196-04f5ba87ff96/image.png)


alter table employees add (nickname varchar(30) default '철수');

컬럼 구조 변경하기

데이터의 Type, 길이, Default 값 등을 변경

alter table 테이블_이름 modify 컬럼_이름 데이터_타입;

예시

alter table employees modify id varchar(30);

컬럼 이름 변경

alter table 테이블_이름 rename column 이전_컬럼_이름 to 새로운_컬럼_이름;

예시

alter table employees rename column hphone to handphone;

테이블 이름 변경하기

rename 이전_테이블_이름 to 신규_테이블_이름;

예시

rename table employees to emp99;

테이블 삭제

Purge 구문 없이 사용하면 테이블이 휴지통으로 이동하고, Purge 구문을 사용하면 영구 삭제됨

drop table 테이블_이름 purge;

예시

drop table emp99;

데이터베이스란?

데이터를 저장해두고, 필요시 이것을 가져다가 사용하거나 수정/조회/삭제 하기 위한 자료 저장소

데이터베이스의 목표

지속적 데이터 관리 및 보호와, 안정성 및 무결성의 보장

데이터베이스의 특징

• 실시간 접근
• 동적인 변화에 대한 유연한 대처
• 동시 공용성 (특정인의 전유물이 되어선 안됨)
• 실제 데이터에 의한 참조

SQL?

Structured Query Language의 준말로, DataBase로부터 데이터를 조회/삭제/수정 등의 작업을 수행할 때 사용하는 질의 언어

질의란? 데이터베이스에게 어떠한 질문을 하여 결과를 도출하기

주요 SQL 구문

DDL (Data Definition Language)

• 데이터 정의어 (CREATE, ALTER, DROP)
• 데이터 구조를 정의(CREATE)하고, 구조 변경(ALTER) 및 테이블 삭제(DROP) 등을 수행하기 위한 문법
• 실행 주체: 객체 단위

DML (Data Manipulation Language)

• 데이터 조작어 (INSERT, UPDATE, DELETE)
• 행 단위로 데이터를 조작하기 위한 언어로 행을 추가(INSERT)하거나 특정 컬럼에 대한 데이터 수정(UPDATE), 삭제(DELETE) 등을 의미
• 실행 주체: 행 단위

DCL (Data Control Language)

• 데이터 제어문 (GRANT, REVOKE)
• 데이터 접근 권한 등에 대한 부여(GRANT), 접근 권한 삭제(REVOKE) 등의 목적으로 사용되는 언어
• 실행 주체: 사용자 단위

DQL (Data Query Language)

• 데이터 질의어 (SELECT)
• 질의(Query)를 통한 데이터 내용을 조회하기 위한 언어

TCL (Transaction Control Language)

• 트랜잭션 (COMMIT, ROLLBACK)
• 데이터를 영구적으로 저장하는 동작(Commit), DML 구문에 대하여 작업 취소하는 동작(RollBack) 등을 수행

DBMS란?

데이터베이스를 관리하기 위하여 필요한 SW 패키지의 집합체

DBMS 주요 기능

• 데이터의 추가/조회/변경/삭제가 가능해야함
• 데이터의 무결성이 유지되어야함
• 트랜잭션 관리가 되어야함
• 데이터 백업 및 복원이 가능해야함
• 데이터 보안을 중요시 생각함

데이터베이스 객체

데이터베이스를 구성하고 있는 개별적인 단위 요소

• 테이블: 행과 열로 구성된 2차원적인 표
• 시퀀스: 정수형 번호표 생성기
• 인덱스: 데이터 검색을 빨리 하기 위하여 만들어 둔 개념
• 프로시저: 반환 타입이 없는 객체
• 함수: 반환 타입이 있는 객체

사용자 라우트는 로그인, 로그아웃, 등록으로 구성된다. 인증을 완료한 사용자는 이벤트를 생성, 변경, 삭제할 수 있으며, 인증을 거치지 않은 사용자는 생성된 이벤트를 확인하는 것만 가능하다.

사용자 라우트

routes 폴더의 users.py에 사용자 라우트를 정의해보자

먼저 등록 라우트이다. 등록 라우트는 애플리케이션에 내장된 데이터베이스를 사용하며, 사용자를 등록하기 전 데이터베이스에 비슷한 이메일이 존재하는지 확인한다.

from fastapi import APIRouter, HTTPException, status
from models.users import User, UserSignIn

user_router = APIRouter(
    tags = ["User"]
)

users = {}

@user_router.post("/signup")
async def sign_new_user(data: User) -> dict:
    if data.email in users:
        raise HTTPException(
            status_code=status.HTTP_409_CONFLICT,
            detail="User wuth supplied username exists"
        )
    users[data.email] = data
    return {
        "message":"User successfully registered"
    }

다음은 로그인(/signin) 라우트이다.

이 라우트는 로그인하려는 사용자가 데이터베이스에 존재하는지를 먼저 확인하고, 없으면 예외를 발생시킨다.

사용자가 존재하면 패스워드가 일치하는지 확인해서 성공 또는 실패 메시지를 반환한다.

@user_router.post("/signin")
async def sign_user_in(user: UserSignIn) -> dict:
    if user.email not in users:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="User does not exist"
        )
    if users[user.email].password != user.passward:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Wrong credentials passed"
        )

    return {
        "message":"User signed in successfully"
    }

이제 사용자 처리용 라우트를 정의했으니, main.py에 라우트를 등록하고 애플리케이션 실행을 해보자.

from fastapi import FastAPI
from routes.users import user_router

import uvicorn

# FastAPI() 인스턴스를 만들고 앞서 정의한 라우트 등록
app = FastAPI()

# 라우트 등록
app.include_router(user_router, prefix="/user")

if __name__=="__main__":
    # uvicorn.run() 메서드를 사용해 8000번 포트에서 애플리케이션을 실행하도록 설정
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

이제 실행해보자.

python3 main.py

테스트

애플리케이션이 실행됐으니 사용자 라우트를 테스트해보자

사용자 등록 테스트

curl -X 'POST' \
'http://127.0.0.1:8000/user/signup' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email":"fastapi@packt.com",
"password":"Stro0ng!",
"username":"FastPackt"
}'

(결과)

{"message":"User successfully registered"}%                           

로그인 테스트

정상 로그인 케이스

curl -X 'POST' \
'http://127.0.0.1:8000/user/signin' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email":"fastapi@packt.com",
"password":"Stro0ng!"
}'

(결과)

{"message":"User signed in successfully"}%               

비정상 로그인 케이스(패스워드 틀림)

curl -X 'POST' \
'http://127.0.0.1:8000/user/signin' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"email":"fastapi@packt.com",
"password":"password!"
}'

(결과)

{"detail":"Wrong credentials passed"}%              

이벤트 라우트

사용자 라우트가 준비됐으니 이제 이벤트 라우트를 구현해야한다.

routes 폴더의 events.py를 열어서 다음과 같이 의존 라이브러리를 임포트하고 이벤트 라우트를 정의한다.

from fastapi import APIRouter, Body, HTTPException, status
from models.events import Event
from typing import List

event_router = APIRouter(
    tags = ["Events"]
)

events = []

모든 이벤트를 추출하거나 특정 ID의 이벤트만 추출하는 라우트를 정의한다.

@event_router.get("/", response_model=Event)
async def retrieve_all_events() -> List[Event]:
    if len(events)==0: 
        raise HTTPException(
        status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
        detail="No events found"
    )
    return events

@event_router.get("/{id}", response_model=Event)
async def retrieve_event(id: int) -> Event:
    for event in events:
        if event.id == id:
            return event

    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Event with supplied ID does not exist"
    )

이제 이벤트 생성 및 삭제 라우트를 정의하자.

첫 번째 라우트는 이벤트 생성, 두 번째는 데이터베이스에 있는 단일 이벤트 삭제, 세 번째는 전체 이벤트 삭제이다.

@event_router.post("/new")
async def create_event(body: Event = Body(...)) -> dict:
    events.append(body)
    return {
        "message":"Event created successfully"
    }

@event_router.delete("/{id}")
async def delete_event(id: int) -> dict:
    for event in events:
        if event.id == id:
            events.remove(event)
            return {
                "message" : "Event deleted successfully"
            }

    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Event with supplied ID does not exist"
    )

@event_router.delete("/")
async def delete_all_events() -> dict:
    events.clear()
    return {
        "message":"Events deleted successfully."
    }

이제 main.py의 라우트 설정을 변경해서 이벤트 라우트를 추가하자.

from fastapi import FastAPI
from routes.users import user_router
from routes.events import event_router # event 라우트

import uvicorn

# FastAPI() 인스턴스를 만들고 앞서 정의한 라우트 등록
app = FastAPI()

# 라우트 등록
app.include_router(user_router, prefix="/user")
app.include_router(event_router, prefix="/event") # event 라우트 등록

if __name__=="__main__":
    # uvicorn.run() 메서드를 사용해 8000번 포트에서 애플리케이션을 실행하도록 설정
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

테스트

이제 이벤트 라우트도 테스트해보자.

• GET 라우트 : 다음 명령을 실행하여 이벤트를 조회해보자. ``` curl -X 'GET'
  'http://127.0.0.1:8000/event/' \
• H 'accept: application/json'

이벤트가 없기에, 500 에러가 발생하고 아래와 같은 출력을 확인할 수 있다.

{"detail":"No events found"}%                                     

• POST 라우트 : 다음 명령을 실행하여 _이벤트를 추가_해보자. ``` curl -X 'POST'
  'http://127.0.0.1:8000/event/new' \
• H 'accept: application/json' \
• H 'Content-Type: application/json' \
• d '{ "id":1, "title":"FastAPI Book Launch", "image":"https://linktomyimage.com/image.png", "description": "We will be discussing the contents of the FastAPI book in this event.Ensure to come with your own copy to win gifts!", "tags":["python", "fastapi", "book", "launch"], "location": "Google Meet" }'

(결과)

{"message":"Event created successfully"}%   

• GET 라우트 : 다음 명령을 실행하여 생성한 이벤트를 추출해보자. ``` curl -X 'GET'
  'http://127.0.0.1:8000/event/1' \
• H 'accept: application/json'

(결과)

앞서 추가한 이벤트가 그대로 표시된다.

{
  "id":1,
  "title":"FastAPI Book Launch",
  "image":"https://linktomyimage.com/image.png",
  "description":"We will be discussing the contents of the FastAPI book in this event.Ensure to come with your own copy to win gifts!",
  "tags":["python","fastapi","book","launch"],
  "location":"Google Meet"
}%  

• DELETE 라우트 : 다음 명령어를 실행하여 이벤트를 삭제해보자. ``` curl -X 'DELETE'
  'http://127.0.0.1:8000/event/1' \
• H 'accept: application/json'

(결과)

{"message":"Event deleted successfully"}%                             

동일한 삭제 명령을 다시 실행해보자.

{"detail":"Event with supplied ID does not exist"}%   

해당 ID의 이벤트가 존재하지 않기 때문문에 detail이 출력된다.

여기까지 이벤트 플래너 애플리케이션의 라우트와 모델을 성공적으로 구현했으며, 테스트를 통해 제대로 실행되는지도 확인했다.

• database 폴더

  • connection.py : 데이터베이스 추상화와 설정에 사용하는 파일

• routes 폴더

  • events.py : 이벤트 생성, 변경, 삭제 등의 처리를 위한 라우팅
  • users.py : 사용자 등록 및 로그인 처리를 위한 라우팅

• models 폴더

  • events.py : 이벤트 처리용 모델을 정의
  • users.py : 사용자 처리용 모델을 정의

이벤트 플래너 애플리케이션 개발

등록된 사용자는 이벤트를 추가, 변경, 삭제할 수 있으며 애플리케이션이 자동으로 만든 이벤트 페이지에서 생성된 이벤트를 확인할 수 있다.

등록된 사용자와 이벤트는 모두 고유한 ID를 가지며, 이를 통해 사용자와 이벤트가 중복되는 것을 방지할 수 있다.

먼저 가상환경을 활성화 하자

python3 -m venv venv
source venv/bin/activate

필요한 라이브러리도 설치하고

pip install fastapi uvicorn "pydantic[email]"

필요한 라이브러리를 requirements.txt에 저장하자

pip freeze > requirements.txt

이제 필요한 라이브러리가 포함된 개발 환경이 모두 준비됐다. 이제 애플리케이션 모델을 구현해보자

모델 구현

모델 구현은 이벤트 모델과 사용자 모델의 정의부터 시작한다. 이 모델들은 데이터가 어떤 방식으로 입력 및 저장되고 애플리케이션에 표현되는지를 정의한다.

이벤트 모델

이벤트 모델은 models 폴더의 events.py에 정의한다.

from pydantic import BaseModel
from typing import List

class Event(BaseModel):
    id: int
    title: str
    image: str
    description: str
    tags: List[str]
    location: str

• id : 자동 생성되는 고유 식별자
• title : 이벤트 타이틀
• image : 이벤트 이미지 배너의 링크
• description : 이벤트 설명
• tags : 그룹화를 위한 이벤트 태그
• location : 이벤트 위치

Event 클래스 안에 Config 서브 클래스를 추가한다. 이 클래서는 문서화할 때 샘플 데이터를 보여주기 위한 용도이다.

    class Config:
        schema_extra = {
            "example" : {
                "title" : "FastAPI Book Launch",
                "image" : "https://linktomyimage.com/image.png",
                "description" : "We will be discussing the contents of the FastAPI book in this event. Ensure to come with your own copy to win gifts!",
                "tags" : ["python", "fastapi", "book", "launch"],
                "location" : "Google Meet"
            }
        }

이 코드는 샘플 데이터를 정의하며, API를 통해 신규 이벤트를 생성할 때 참고할 수 있다.

사용자 모델

사용자 모델(User)을 models 폴더의 users.py 파일에 정의한다.

from pydantic import BaseModel, EmailStr
from typing import Optional, List
from models.events import Event

class User(BaseModel):
    email: EmailStr
    password: str
    events: Optional[List[Event]]

• email : 사용자 이메일
• password : 사용자 패스워드
• events : 해당 사용자가 생성한 이벤트, 처음에는 비어있다.

데이터를 어떻게 저장하고 설정하는지 보여주는 샘플 데이터를 만든다.

    class Config:
        schema_extra = {
            "example" : {
                "email" : "fastapi@packt.com",
                "passward" : "strong!!!",
                "events" : [],
            }
        }

마지막으로 사용자 로그인 모델(UserSignIn)을 만든다.

class UserSignIn(BaseModel):
    email: EmailStr
    passward: str

    class Config:
        schema_extra = {
            "example" : {
                "email" : "fastapi@packt.com",
                "passward" : "strong!!!",
                "events" : [],
            }
        }

이 폴더에 모든 Jinja 관련 파일이 저장된다.

Jinja2 관련 패키지들을 먼저 설치하자

pip3 install jinja2 python-multipart

templates 폴더를 생성하자

mkdir templates

이제 templates 폴더 안에 home.html,todo.html 이라는 두 개의 파일을 만든다.

cd templates
touch {home,todo}.html

• home.html : 애플리케이션 홈 페이지용
• todo.html : todo 페이지용

이제 FastAPI 애플리케이션이 Jinja를 사용하도록 설정해보자

1. todo API 컴포넌트(todo.py)의 POST 라우트 수정

from fastapi import APIRouter, Path, HTTPException, status, Request, Depends
from fastapi.templating import Jinja2Templates
from model import Todo, TodoItem, TodoItems

todo_router = APIRouter()

todo_list = []

templates = Jinja2Templates(directory="templates/")

@todo_router.post("/todo")
async def add_todo(request: Request, todo: Todo = Depends(Todo.as_form)):
    todo.id = len(todo_list) + 1
    todo_list.append(todo)
    return templates.TemplateResponse("todo.html",
                                      {
                                          "request":request,
                                          "todos":todo_list
                                      })

2. GET 라우트 수정

@todo_router.get("/todo", response_model = TodoItems)
async def retreive_todos(request:Request):
    return templates.TemplateResponse("todo.html",
                                    {
                                        "request":request,
                                        "todos":todo_list
                                    })

@todo_router.get("/todo/{todo_id}")
async def get_single_todo(request:Request, todo_id: int =Path(..., title="The ID of the todo to retrieve")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return templates.TemplateResponse("todo.html",
                                {
                                    "request":request,
                                    "todos":todo_list
                                })
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist"
    )

이 코드는 Jinja가 template 폴더를 참조해서 그 안에 있는 특정 템플릿을 사용하도록 지정한다. 템플릿은 templates.TemplateResponse() 메서드를 통해 전달된다. (todo를 추가하는 POST 메서드는 의존성을 사용해서 입력값을 전달한다.)

3. model.py의 Config 서브 클래스 추가

from pydantic import BaseModel
from typing import List, Optional
from fastapi import Form

class Item(BaseModel):
    item: str
    status: str

class Todo(BaseModel):
    id: Optional[int] = None
    item: str

    @classmethod
    def as_form(
        cls,
        item: str = Form(...)
    ):
        return cls(item=item)

4. home.html 파일의 문서 유형 선언

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta content="IE=edge" http-equiv="X-UA-Compatible">
    <meta content="width=device-width, initial-scale=1.0" name="viewport">
    <title>Packt Todo Application</title>
    <link crossorigin="anonymous" href="https://stackpath.bootstrapcdn.com/bootstrap/4.1.0/css/bootstrap.min.css"
          integrity="sha384-9gVQ4dYFwwWSjIDZnLEWnxCjeSWFphJiwGPXr1jddIhOegiu1FwO5qRGvFXOdJZ4" rel="stylesheet">
    <link crossorigin="anonymous" href="https://use.fontawesome.com/releases/v5.0.10/css/all.css"
          integrity="sha384-+d0P83n9kaQMCwj8F4RJB66tzIwOKmrdb46+porD/OvrJ+37WqIM7UoBtwHO6Nlg" rel="stylesheet">
</head>

5. 템플릿 바디를 작성

container-fluid Class에 block 태그를 사용해 todo_container를 추가한다.

<body>
<header>
    <nav class="navar">
        <div class="container-fluid">
            <center>
                <h1>Packt Todo Application</h1>
            </center>
        </div>
    </nav>
</header>
<div class="container-fluid">
    {% block todo_container %}{% endblock %}
</div>
</body>
</html>

6. todo.html을 열어서 다음과 같은 템플릿을 작성

{% extends "home.html" %}

{% block todo_container %}
<main class="container">
    <hr>
    <section class="container-fluid">
        <form method="post">
            <div class="col-auto">
                <div class="input-group mb-3">
                    <input aria-describedby="button-addon2" aria-label="Add a todo" class="form-control" name="item"
                           placeholder="Purchase Packt's Python workshop course" type="text"
                           value="{{ item }}"/>
                    <button class="btn btn-outline-primary" data-mdb-ripple-color="dark" id="button-addon2"
                            type="submit">
                        Add Todo
                    </button>
                </div>
            </div>
        </form>
    </section>
    {% if todo %}
    <article class="card container-fluid">
        <br/>
        <h4>Todo ID: {{ todo.id }} </h4>
        <p>
            <strong>
                Item: {{ todo.item }}
            </strong>
        </p>
    </article>
    {% else %}
    <section class="container-fluid">
        <h2 align="center">Todos</h2>
        <br>
        <div class="card">
            <ul class="list-group list-group-flush">
                {% for todo in todos %}
                <li class="list-group-item">
                    {{ loop.index }}. <a href="/todo/{{ loop.index }}"> {{ todo.item }} </a>
                </li>
                {% endfor %}
            </ul>
        </div>
        {% endif %}
    </section>
</main>
{% endblock %}

todo 템플릿이 home 템플릿을 상속한다. 또한 todo_container 블록을 정의해서 부모 템플릿이 이 템플릿의 콘텐츠를 표시할 수 있게 한다.

todo 템플릿은 모든 todo를 추출하는 라우트와 단일 todo 추출하는 라우트 모두에서 사용된다. 결과적으로 라우트에 따라 다른 콘텐츠를 렌더링하게 되는 것이다.

이제 웹 브라우저에 들어가 변경 내용이 반영되었는지 확인해보자.

홈 페이지가 제대로 작동하는지 확인하기 위해 todo 아이템을 하나 추가해보자

잘 작동된다.

존재하지 않는 리소스나 권한이 없는 페이지에 접근하는 경우 요청 시 오류가 발생하며 서버 자체에서 오류가 발생하기도 한다.

FastAPI에서 오류는 FastAPI의 HTTPException 클래스를 사용해 예외를 발생시켜 처리한다.

HTTP 예외 HTTP 예외는 요청 흐름상에 발생하는 오류나 문제를 가리키는 이벤트

HTTPException 클래스는 다음 세 개의 인수를 받는다

• status_code : 예외 처리 시 반환할 상태 코드
• detail : 클라이언트에게 전달할 메시지
• headers : 헤더를 요구하는 응답을 위한 선택적 인수

존재하지 않는 todo를 추출하면 404가 아닌 200 응답이 반환된다.

HTTPException 클래스를 사용해 라우트를 변경하면 적절한 응답 코드와 함께 상태 메시지도 반환할 수 있다. todo.py에서 추출, 변경, 삭제 라우트를 다음과 같이 변경하자.

from fastapi import APIRouter, Path, HTTPException, status

...

@todo_router.get("/todo/{todo_id}")
async def get_single_todo(todo_id: int =Path(..., title="The ID of the todo to retrieve")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {
                "todo":todo
            }
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist"
    )


@todo_router.put("/todo/{todo_id}")
async def update_todo(todo_data: TodoItem, todo_id: int = Path(..., title="The ID of the todo to be updated")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            todo.item = todo_data.item
            return {
                "message" : "Todo updated successfully"
            }
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist"
    )

@todo_router.delete("/todo/{todo_id}")
async def delete_single_todo(todo_id: int) -> dict:
    for index in range(len(todo_list)):
        todo = todo_list[index]
        if todo_id == todo_id:
            todo_list.pop(index)
            return {
                "message" : "Todo deleted successfully"
            }
    raise HTTPException(
        status_code=status.HTTP_404_NOT_FOUND,
        detail="Todo with supplied ID doesn't exist"
    )

이제 다시 한번 존재하지않는 todo를 추출해주자.

마지막으로 데코레이터 함수에 status_code 인수를 추가해 기본 응답 코드(200)를 다른 코드로 변경해보자.

@todo_router.post("/todo", status_code=201)
async def add_todo(todo: Todo) -> dict:
    todo_list.append(todo)
    return {
        "message":"Todo added successfully!"
    }

참고로 요청 성공을 의미하는 기본 상태 코드는 200이다.

라우트 경로 정의

@app.get("/todo")
async def retreive_todo() -> dict:
    '''

    현재 DB에 있는 모든 todo 아이템의 목록을 반환
    '''
    return {
        "todos" : todo_list
    }

모든 todo를 추출해서 배열로 반환하는 라우트를 ID없이 todo 아이템만 반환하도록 변경하기 위해서 새로운 모델을 추가한다.

from typing import List

...

class TodoItems(BaseModel):
    todo: List[TodoItem]

    class Config:
        schema_extra = {
            "example": {
                "todos" : [
                    {
                        "item" : "Example schema 1"
                    },
                    {
                        "item" : "Example schema 2"
                    },
                ]
            }
        }

이제 todo.py에 있는 라우트에 다음과 같은 응답 모델을 추가해보자.

from model import Todo, TodoItem, TodoItems

@todo_router.get("/todo", resposn_model = TodoItems)
async def retreive_todos() -> dict:
    return {
        "todos":todo_list
    }

애플리케이션 실행

uvicorn main:app --host=127.0.0.1 --port 8000 --reload

이제 새로운 todo를 추가해주자.

curl -X 'POST' \
'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id": 1,
"item": "This todo will be retrieved without exposing my ID!"
}'

todo를 추출해보자

curl -X 'GET' \
'http://127.0.0.1:8000/todo' \
-H 'accept: application/json'

결과

API 라우트 경로가 반환하는 데이터의 템플릿 역할을 하며, 서버에 전달된 요청을 기준으로 적절한 응답을 렌더링 하기 위해 pydantic을 사용한다.

오류 처리

애플리케이션에서 발생하는 오류를 처리하는 로직과 방법으로, 오류 처리에는 적절한 오류 상태 코드와 오류 메시지가 포함된다.

FastAPI의 응답

응답은 API 처리 과정의 한 부분으로, HTTP 메서드를 통해 API와 상호 작용하며 API로부터 받은 결과를 가리킨다. API 응답은 JSON, XML, 문서 형식이며 헤더와 바디로 구성된다.

응답 헤더

요청 상태 및 응답 바디 전달을 안내하는 정보로 구성되며, 대표적으로는 반환하는 콘텐츠 유형이 무엇인지 클리아언트에게 알려주는 역할을 함

응답 바디

응답 바디는 서버가 클라이언트에게 반환하는 데이터로, 대표적인 예로 application/json이 있다. (todo_list가 응답바디에 해당한다.)

상태 코드

서버가 반환한 응답에 포함되는 짧은 고유 코드로, 클라이언트가 보낸 요청의 상태를 나타낸다.

• 1XX : 요청을 받았다.
• 2XX : 요청을 성공적으로 처리했다. (ex. 200)
• 3XX : 요청을 리다이렉트했다.
• 4XX : 클라이언트 측에 오류가 있다. (ex. 404)
• 5XX : 서버 측에 오류가 있다. (ex. 500)

UPDATE 라우트의 요청 바디용 모델

class TodoItem(BaseModel):
    item: str

    class Config:
        schema_extra = {
            "example": {
            "item": "Read the next chapter of the book."
            }
        }

todo 변경을 위해 todo.py에 추가

from model import Todo, TodoItem

...

@todo_router.put("/todo/{todo_id}")
async def update_todo(todo_data: TodoItem, todo_id: int = Path(..., title="The ID of the todo to be updated")) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            todo.item = todo_data.item
            return {
                "message" : "Todo updated successfully"
            }

    return {
        "message" : "Todo with supplied ID doesn't exist"
    }

새로 추가한 라우트를 테스트하자.

curl -X 'POST' \
'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"id":1, "item":"Example Schema!"}'

잘 적용된거같다.

이제 PUT 요청을 보대서 추가한 아이템을 수정해보자

curl -X 'PUT' \
'http://127.0.0.1:8000/todo/1' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"item":"Read the next chapter of the book"}'

PUT 요청에 의해 UPDATE 라우트가 정상 작동했다.

DELETE 라우트의 요청 바디용 모델

@todo_router.delete("/todo/{todo_id}")
async def delete_single_todo(todo_id: int) -> dict:
    for index in range(len(todo_list)):
        todo = todo_list[index]
        if todo_id == todo_id:
            todo_list.pop(index)
            return {
                "message" : "Todo deleted successfully"
            }
    return {
        "message" : "Todo with supplied ID doesn't exist"
    }

@todo_router.delete("/todo")
async def delete_all_todo() -> dict:
    todo_list.clear()
    return {
        "message" : "Todo deleted successfully"
    }

이제 테스트 해보자.

먼저 신규 todo 아이템을 넣어주자

curl -X 'POST' \
'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"id":1, "item":"Example Schema!"}'

이제 DELETE 시켜보자.

curl -X 'DELETE' \
'http://127.0.0.1:8000/todo/1' \
-H 'accept: application/json'

삭제됐다!

요청 바디란 POST와 UPDATE 등 라우팅 메서드를 사용해 API로 전달되는 데이터다.

curl -X 'POST' 'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"id":2, "item":"Validation"}'

에서 요청 바디는

{"id":2, "item":"Validation"}

이다.

FastAPI는 추가 검증할 수 있는 Body 클래스를 제공한다.

모델은 API 라우트와 요청 바디의 유형을 자동으로 문서화할 때도 사용된다.

FastAPI 자동 문서화

• 스웨거
• ReDoc

FastAPI는 다음 총 2가지의 문서 유형을 제공하는데, 스웨거는 앞서 설명했던, http://127.0.0.1:8000/docs이다.

ReDoc은 모델, 라우트, API에 관한 정보를 더 직관적이로 상세하게 전달한다. http://127.0.0.1:8000/redoc

샘플 데이터를 추가해보자.

class Todo(BaseModel):
    id: int
    item: str

    class Config:
        schema_extra = {
            "example": {
                "id":1,
                "item": "Exmple Schema!"
            }
        }

경로 매개변수는 리소스를 식별하기 위해 API 라우팅에 사용된다. 이 매개변수는 식벽자 역할을 하며 웹 애플리케이션이 추가 처리를 할 수 있도록 연결 고리가 되도록 한다.

앞서 만든 todo_list에서 하나의 todo 작업만 할 수 있는 라우트를 만들자 예제에서는 경로 매개변수가 todo_id가 된다.

@todo_router.get("/todo/{todo_id}")
async def get_single_todo(todo_id: int) -> dict:
    for todo in todo_list:
        if todo.id == todo_id:
            return {
                "todo":todo
            }
    return {
        "message":"Todo with supplied ID doesn't exist"
    }

추가한 라우트를 테스트 해보자. (리액트에서 id 3을 출력하도록 코딩했다)

잘된다.

이제 Path 클래스를 추가해보자. Path는 FastAPI가 제공하는 클래스로, 라우트 함수에 있는 다른 인수와 경로 매개변수를 구분하는 역할을 한다. Path 클래스는 스웨거와 ReDoc 등으로 OpenAPI 기반 문서를 자동 생성할 때 라우트 관련 정보를 함께 문서화하도록 돕는다.

from fastapi import APIRouter, Path

...


async def get_single_todo(todo_id: int =Path(..., title="The ID of the todo to retrieve")) -> dict:

Path(..., kargs) Path 클래스는 첫 인수로 None 또는 ... 을 받을 수 있는데, 첫 인수가 ...이면 경로 매개변수를 반드시 지정해야한다. gt, le와 같은 검증 기호를 사용해, 경로 매개변수에 사용된 값이 특정 범위에 있는 숫자인지 검증도 가능하다.

쿼리 매개변수

쿼리 매개변수는 선택 사항이며 보통 URL에서 ? 뒤에 온다. 제공된 쿼리를 기반으로 특정한 값을 반환하거나 요청을 필터링할 때 사용된다.

예시를 보자

async query_route(query: str = Query(None)):
    return query

FastAPI에서는 정의된 데이터만 전송되도록 요청 바디를 검증할 수 있다. 이는 요총 데이터가 적절한지 확인하고 악의적인 공격의 위험을 줄여줄 수 있기에 매우매우 중요하다.

pydantic? 파이썬의 타입 어노테이션을 사용해 데이터를 검증하는 파이썬 라이브러리

FastAPI에서 모델은 데이터가 어떻게 전달되고 처리돼야 하는지를 정의하는 구조화된 클래스로, 모델은 pydantic의 BaseModel 클래스의 하위 클래스로 생성된다.

모델은 요청 바디 객체와 요청 응답 객체의 유형에 관한 힌트를 제공한다.

pydantic을 사용해 요청 바디를 검증하는 부분

from pydantic import BaseModel

class Todo(BaseModel):
    id: int
    item: str

이 모델을 POST 라우트에 사용해보자

from fastapi import APIRouter
from model import Todo # todo.py 파일에 모델 임포트

todo_router = APIRouter()

todo_list = []

@todo_router.post("/todo")
async def add_todo(todo: Todo) -> dict: #todo에 Todo 사용
    todo_list.append(todo)
    return {
        "message":"Todo added successfully!"
    }

@todo_router.get("/todo")
async def retreive_todos() -> dict:
    return {
        "todos":todo_list
    }

빈 딕셔너리를 요청 바디로 보내서 모델이 제대로 검증되는지 확인하자

curl -X 'POST' 'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{}'

성공했다.

성공하면...안되는데..?

모델과 일치하는 데이터를 보내보자

curl -X 'POST' 'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"id":2, "item":"Validation"}'

중첩 모델

pydantic 모델은 다음과 같이 중첩해서 정의할 수 있다.

from pydantic import BaseModel

class Item(BaseModel):
    item: str
    status: str

class Todo(BaseModel):
    id: int
    item: Item

결과적으로 Todo형의 데이터는

{
  "id": 1,
  "item": {
    "item": "Nested models",
    "status": "completes"
  }
}

라우트는 HTTP 요청 메서드의 요청을 수락하고 선택적으로 인수를 받을 수 있도록 정의됨 요청이 특정 라우트로 전달되면 애플리케이션은 라우트 처리기(Route handler)가 요청을 처리하기 전에 해당 라우트가 정의되어 있는지 확인함 Route handler는 서버로 전송된 요청을 처리하는 함수로, Route handler의 예로는 요청을 받아 DB에서 특정 데이터를 추출하는 함수가 있음

HTTP 요청 메서드 HTTP 메서드 처리 유형을 정의하는 식별자로, 표준 메서드에는 GET, POST, PUT, PATCH, DELETE 등이 있음

라우팅 예

• 단일 라우트 애플리케이션 예시

  from fastapi import FastAPI
  

app = FastAPI()

@app.get("/")

async def welcom() -> dict: return { "message":"Hello World" }

# APIRouter 클래스를 사용한 라우팅
APIRouter 클래스는 다중 라우팅을 위한 경로 처리 클래스로 애플리케이션 라우팅과 로직을 독립적으로 구성하고 모듈화 할 수 있음

#### 예시
```python
from fastapi import APIRouter

router = APIRouter()

@router.get("/hello")
async def say_hello() -> dict:
    return {
        "message":"Hello!"
    }

(참고) 클라이언트와 다른 포트를 사용할 경우,

CORS 이슈: 클라이언트(리액트 앱)와 서버(FastAPI)가 다른 포트에서 실행되고 있을 경우, CORS(Cross-Origin Resource Sharing) 정책 때문에 문제가 발생할 수 있습니다. 서버에서 CORS를 허용하도록 설정해야 합니다. FastAPI에서는 fastapi.middleware.cors.CORSMiddleware를 사용하여 CORS를 설정할 수 있습니다. 다음은 CORS 설정 예시입니다:

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # 리액트 앱의 URL
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/")
async def read_root():
    return {"Hello": "World"}

새로운 라우트와 라우트 처리기 만들기

새로운 파일 생성

touch todo.py

다음은 APIRouter를 활용한 예시 코드이다.

from fastapi import APIRouter

todo_router = APIRouter()

todo_list = []

@todo_router.post("/todo")
async def add_todo(todo: dict) -> dict:
    todo_list.append(todo)
    return {
        "message":"Todo added successfully!"
    }

@todo_router.get("/todo")
async def retreive_todos() -> dict:
    return {
        "todos":todo_list
    } 

APIRouter는 FastAPI 클래스와 동일한 방식으로 작동하지만, 정의한 라우트를 FastAPI() 인스턴스에 추가해야 외부에서 접근 가능하다.

main.py 파일에 다음과 같이 todo.py 파일에서 생성한 todo_router를 import하고 FastAPI() 인스턴스의 include_router() 메서드를 사용해야한다.

from fastapi import FastAPI
from todo import todo_router

from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # 리액트 앱의 URL
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/")
async def read_root():
    return {"Hello": "World"}

app.include_router(todo_router)

결과를 한번 볼까? (난 React로 심플하게 확인할 수 있는 코드를 짰다)

이제 POST 요청을 전달해서 todo_list에 추가해보자

curl -X 'POST' \
'http://127.0.0.1:8000/todo' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"id":1,
"item":"First Todo is to finish this book!"
}'

그럼

{"message":"Todo added successfully!"}%                  

라는 메시지가 출력될꺼다.

프론트엔드에서 확인해보니,

잘 적용된거 같다.

Python 가상 환경 생성

파이썬은 가상 환경을 통해 프로젝트마다의 독립된 환경을 구축할 수 있다. 하나의 PC안에서 독립된 가상 환경을 여러 개 만들수 있어, 하나의 PC안에 서로 다른 버전의 파이썬과 라이브러리를 쉽게 설치해 사용할 수 있다.

가상 환경 생성

python3 venv -m myapi

가상 환경 활성화

source myapi/bin/activate

가상 환경에 정상적으로 진입했다면, 명령 프롬프트 왼쪽에 (myapi) 프롬프트가 보이는지 확인하자.

가상 환경에 FastAPI 설치하기

myapi 가상 환경에 진입한 상태에서 pip3 install fastapi 명령을 입력하면된다

pip3 install fastapi

파이보 프로젝트

웹 브라우저에서 "안녕하세요 파이보"를 출력해주는 첫 번째 프로그램을 만들어보겠다.

Hello API 만들기

다음과 같이 main.py 파일을 작성하자.

from fastapi import FastAPI

app = FastAPI()

@app.get("/hello")
def hello():
    return {"message":"안녕하세요 파이보"}

FastAPI 클래스로 생성한 app 객체가 바로 FastAPI의 핵심 객체이다. 모든 동작은 이 객체로부터 비롯된다. 함수명 위에 @app.get("/hello") 어노테이션은 /hello라는 URL요청이 발생하면 해당 함수를 실행하여 결과를 리턴하라는 의미이다. 따라서 /hello라는 URL이 요청되면 FastAPI는 {"message":"안녕하세요 파이보"}라는 딕셔너리를 리턴할 것이다.

이제 작성한 프로그램을 실행해야한다. FastAPI로 작성한 프로그램을 실행하기 위해서는 FastAPI 프로그램을 구동할 서버가 필요하다. 먼저 uvicorn을 설치하자.

유비콘(Uvicorn)은 비동기 호출을 지원하는 파이썬용 웹 서버이다.

pip3 install uvicorn[standard]

설치가 완료되었다면, 이제 생성한 Hello API를 실행해보자.

uvicorn main:app --reload

그러면 현재 PC에 8000번 포트로 FastAPI서버가 구동된다.

main:app에서 main은 main.py 파일을 의미하고 app는 main.py의 app객체를 의미한다. --reload 옵션은 프로그램이 변경되면 서버 재시작 없이 그 내용을 반영하라는 의미히다.

Hello API 테스트하기

FastAPI가 실행되면 FastAPI로 작성한 API는 /docs URL을 호출하여 테스트해볼 수 있다.

http://127.0.0.1:8000/docs

다음 화면이 나타난다. 이 화면이 바로 FastAPI의 테스트가 가능한 API 문서라고 한다.

main.py에서 작성한 /hello URL에 대한 API가 등록된 것을 볼 수 있다. 해당 API를 누르고 "Try it out" 버튼을 누른 후 "Execute" 버튼을 누르면 Hello API의 동작을 테스트할 수 있다.

hello 함수에서는 딕셔너리를 리턴했지만 FastAPI는 이를 자동으로 json 형태의 응답으로 리턴한다.

한줄평

개좋네.. 예전에 끄적였던 스마트팜 모니터링용으로 구현한 React 서버랑 연동해서 한번 써봐야겠다..

• API를 만들기 위한 파이썬 웹 프레임워크로, API를 만드는데 보다 집중한 프레임워크

  API(Application Programing Interface) 요청과 응답을 처리하는 서비스(기능)

• FastAPI로 작성한 API는 React와 같은 Frontend 웹 프레임워크나 iOS, Android에서도 사용할 수 있음

• Starlette라는 비동기 프레임워크를 통해 파이썬 웹 프레임워크 중 가장 빠른 속도를 자랑함

• Pydantic을 통해, 입출력을 정의하고 입출력 값의 검증을 빠르고 안전하게 할 수 있음, 그리고 작성한 API는 자동으로 생성되는 API 문서를 통해 손쉽게 테스트할 수 있음

• SQLAlchemy를 사용해 ORM(Object Relational Mapping)을 사용할 수 있음

  SQLAlchemy? 파이썬 오픈 소스 SQL 툴킷 및 객체 관계 매핑(ORM) 라이브러리로, ORM은 데이터베이스의 테이블을 파이썬 객체로 표현하여, 파이썬 코드 내에사 데이터베이스를 좀 더 직관적이고 객체 지향적인 방식으로 다룰 수 있게 해줌

• Core* : SQL 표현 언어를 사용하여 명시적인 SQL 쿼리를 작성할 수 있음

• ORM* : 더 높은 수준의 추상화를 제공하여, 클래스와 객체를 사용하여 데이터베이스 테이블을 매핑하고 조작할 수 있음

*참고 : FastAPI는 파이썬 3.6.X 이상 버전에서 지원함