[2026] TypeScript 인터페이스 | Interface 완벽 가이드

· 22분 읽기 · 수정 중급 튜토리얼
[2026] TypeScript 인터페이스 | Interface 완벽 가이드

이 글의 핵심

TypeScript 인터페이스: Interface Interface 기본·함수 타입.

들어가며

Interface는 객체가 가져야 할 모양(shape)을 적은 규격입니다(인터페이스: 타입이 따라야 할 필드·메서드 약속을 적어 둔 것). 값마다 붙는 명찰을 “이 필드들은 꼭 있어야 한다” 수준으로 맞추는 도구라고 보시면 됩니다.

JavaScript에서 TypeScript로의 전환

“런타임 에러는 프로덕션에서 터진다”는 말이 있습니다. JavaScript로 개발하던 시절, 이 말을 뼈저리게 체감했습니다. 테스트는 다 통과했는데 배포 후 사용자가 이상한 데이터를 입력하면 앱이 터지는 거죠. 특히 팀 프로젝트에서 다른 사람이 작성한 함수의 반환 타입을 잘못 이해해서 버그가 발생하는 일이 잦았습니다. TypeScript를 도입한 후 가장 먼저 느낀 건 안심이었습니다. IDE가 자동완성을 정확히 해주고, 타입이 맞지 않으면 빨간 줄로 미리 알려줍니다. 리팩토링할 때도 “이 함수를 바꾸면 어디가 깨질까?” 걱정할 필요가 없어졌죠. 물론 처음엔 타입 정의 작성이 번거로웠지만, 몇 달 후 그 타입 정의 덕분에 버그를 미리 잡는 경험을 하고 나니 돌아갈 수 없었습니다.

1. Interface 기본

선언

Interface는 객체가 가져야 할 프로퍼티와 타입을 정의합니다: 다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// User 인터페이스 선언
// 객체의 "계약(contract)"을 정의
interface User {
    id: string;      // 필수 프로퍼티: 문자열 타입의 id
    name: string;    // 필수 프로퍼티: 문자열 타입의 name
    age: number;     // 필수 프로퍼티: 숫자 타입의 age
    email: string;   // 필수 프로퍼티: 문자열 타입의 email
}
// ✅ 올바른 사용: 모든 프로퍼티 제공
const user: User = {
    id: "U001",
    name: "홍길동",
    age: 25,
    email: "hong@test.com"
};
// TypeScript 컴파일러가 User 인터페이스와 비교하여 검증
// 모든 필수 프로퍼티가 있고 타입이 일치하므로 통과
// ❌ 컴파일 에러: 프로퍼티 누락
// const user2: User = {
//     id: "U002",
//     name: "김철수"
//     // age와 email이 없음!
// };
// 에러 메시지:
// Type '{ id: string; name: string; }' is not assignable to type 'User'.
// Property 'age' is missing in type '{ id: string; name: string; }'
// ❌ 컴파일 에러: 타입 불일치
// const user3: User = {
//     id: "U003",
//     name: "이영희",
//     age: "25",  // string이지만 number 타입 필요
//     email: "lee@test.com"
// };
// 에러 메시지:
// Type 'string' is not assignable to type 'number'.
// ❌ 컴파일 에러: 추가 프로퍼티
// const user4: User = {
//     id: "U004",
//     name: "박민수",
//     age: 30,
//     email: "park@test.com",
//     phone: "010-1234-5678"  // User에 정의되지 않은 프로퍼티
// };
// 에러 메시지:
// Object literal may only specify known properties

Interface의 역할:

  1. 타입 체크: 컴파일 타임에 객체 구조 검증
  2. 자동 완성: IDE에서 프로퍼티 제안
  3. 문서화: 객체 구조를 명시적으로 표현
  4. 리팩토링: 타입 변경 시 모든 사용처 추적

선택적 프로퍼티

? 기호로 선택적 프로퍼티를 정의할 수 있습니다: 다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며, 함수를 통해 로직을 구현합니다, 조건문으로 분기 처리를 수행합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface User {
    id: string;       // 필수 프로퍼티
    name: string;     // 필수 프로퍼티
    age?: number;     // 선택적 프로퍼티 (있어도 되고 없어도 됨)
    email?: string;   // 선택적 프로퍼티
}
// age?: number는 age: number | undefined와 동일
// ✅ OK: 선택적 프로퍼티 없이 생성
const user1: User = {
    id: "U001",
    name: "홍길동"
    // age와 email이 없지만 선택적이므로 에러 없음
};
// ✅ OK: 선택적 프로퍼티 포함
const user2: User = {
    id: "U002",
    name: "김철수",
    age: 30,
    email: "kim@test.com"
};
// 선택적 프로퍼티 사용 시 주의
function printAge(user: User) {
    // user.age는 number | undefined 타입
    // 직접 사용하면 에러 가능성
    
    // ❌ 위험: age가 undefined일 수 있음
    // console.log(user.age.toFixed(0));  // 런타임 에러 가능
    
    // ✅ 안전: 타입 가드 사용
    if (user.age !== undefined) {
        // 이 블록 안에서 user.age는 number 타입으로 좁혀짐
        console.log(user.age.toFixed(0));
    }
    
    // ✅ 안전: Optional Chaining
    console.log(user.age?.toFixed(0));  // undefined면 undefined 반환
    
    // ✅ 안전: 기본값 제공
    const age = user.age ?? 0;  // undefined면 0 사용
    console.log(age);
}
printAge(user1);  // age 없음
printAge(user2);  // age 있음

선택적 프로퍼티의 장점:

  • 유연한 객체 구조 정의
  • 부분 업데이트 시 유용
  • API 응답처럼 일부 필드가 없을 수 있는 경우

읽기 전용 프로퍼티

readonly 키워드로 변경 불가능한 프로퍼티를 정의할 수 있습니다: 다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface User {
    readonly id: string;  // 읽기 전용: 초기화 후 변경 불가
    name: string;         // 일반 프로퍼티: 변경 가능
    age: number;
}
// 객체 생성 시 초기화
const user: User = {
    id: "U001",      // 초기화 ✅
    name: "홍길동",
    age: 25
};
// 일반 프로퍼티는 변경 가능
user.name = "김철수";  // ✅ OK
user.age = 30;         // ✅ OK
// readonly 프로퍼티는 변경 불가
// user.id = "U002";   // ❌ 컴파일 에러
// 에러 메시지:
// Cannot assign to 'id' because it is a read-only property.
// 실전 예시: 데이터베이스 엔티티
interface Post {
    readonly id: string;           // DB에서 자동 생성된 ID
    readonly createdAt: Date;      // 생성 시간 (변경 불가)
    title: string;                 // 제목 (수정 가능)
    content: string;               // 내용 (수정 가능)
    updatedAt: Date;               // 수정 시간 (수정 가능)
}
const post: Post = {
    id: "POST001",
    createdAt: new Date(),
    title: "첫 게시글",
    content: "내용",
    updatedAt: new Date()
};
// 게시글 수정
post.title = "수정된 제목";        // ✅ OK
post.content = "수정된 내용";      // ✅ OK
post.updatedAt = new Date();       // ✅ OK
// post.id = "POST002";            // ❌ 에러: ID는 변경 불가
// post.createdAt = new Date();    // ❌ 에러: 생성 시간 변경 불가

readonly vs const:

  • readonly: 프로퍼티에 사용 (객체의 속성)
  • const: 변수에 사용 (변수 자체) 아래 코드는 typescript를 사용한 구현 예제입니다. 코드를 직접 실행해보면서 동작을 확인해보세요.
const user: User = { id: "U001", name: "홍길동", age: 25 };
// const: user 변수 자체를 재할당 불가
// user = { ....};  // ❌ 에러
// readonly: user.id 프로퍼티를 변경 불가
// user.id = "U002";  // ❌ 에러

2. 함수 타입

메서드

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Calculator {
    add(a: number, b: number): number;
    subtract(a: number, b: number): number;
    multiply?(a: number, b: number): number;  // 선택적
}
const calc: Calculator = {
    add(a, b) {
        return a + b;
    },
    subtract(a, b) {
        return a - b;
    }
};
console.log(calc.add(10, 5));
console.log(calc.subtract(10, 5));

함수 타입

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// 타입 정의
interface MathOperation {
    (a: number, b: number): number;
}
const add: MathOperation = (a, b) => a + b;
const multiply: MathOperation = (a, b) => a * b;
console.log(add(10, 5));
console.log(multiply(10, 5));

생성자 타입

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며, 함수를 통해 로직을 구현합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface ClockConstructor {
    new (hour: number, minute: number): ClockInterface;
}
interface ClockInterface {
    tick(): void;
}
class DigitalClock implements ClockInterface {
    constructor(h: number, m: number) {}
    tick() {
        console.log("beep beep");
    }
}
function createClock(
    ctor: ClockConstructor,
    hour: number,
    minute: number
): ClockInterface {
    return new ctor(hour, minute);
}
const clock = createClock(DigitalClock, 12, 17);
clock.tick();

3. 인덱스 시그니처

문자열 인덱스

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface StringMap {
    [key: string]: string;
}
const colors: StringMap = {
    red: "#FF0000",
    green: "#00FF00",
    blue: "#0000FF"
};
console.log(colors[red]);
console.log(colors.green);

숫자 인덱스

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 코드를 직접 실행해보면서 동작을 확인해보세요.

// 타입 정의
interface NumberArray {
    [index: number]: string;
}
const fruits: NumberArray = ["사과", "바나나", "오렌지"];
console.log(fruits[0]);
console.log(fruits[1]);

혼합 사용

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Dictionary {
    [key: string]: string | number;
    length: number;
}
const dict: Dictionary = {
    name: "홍길동",
    age: 25,
    length: 2
};

4. Interface 확장

extends

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Person {
    name: string;
    age: number;
}
interface Employee extends Person {
    employeeId: string;
    department: string;
}
const employee: Employee = {
    name: "홍길동",
    age: 30,
    employeeId: "E001",
    department: "개발팀"
};

다중 확장

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Timestamped {
    createdAt: Date;
    updatedAt: Date;
}
interface Identifiable {
    id: string;
}
interface User extends Identifiable, Timestamped {
    name: string;
    email: string;
}
const user: User = {
    id: "U001",
    name: "홍길동",
    email: "hong@test.com",
    createdAt: new Date(),
    updatedAt: new Date()
};

5. Interface 병합

Declaration Merging

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface User {
    name: string;
}
interface User {
    age: number;
}
const user: User = {
    name: "홍길동",
    age: 25
};

라이브러리 확장

아래 코드는 typescript를 사용한 구현 예제입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 코드를 직접 실행해보면서 동작을 확인해보세요.

interface Window {
    myCustomProperty: string;
}
window.myCustomProperty = "Hello!";
console.log(window.myCustomProperty);

6. 클래스와 Interface

implements

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Animal {
    name: string;
    makeSound(): void;
}
class Dog implements Animal {
    name: string;
    
    constructor(name: string) {
        this.name = name;
    }
    
    makeSound() {
        console.log("멍멍!");
    }
}
const dog = new Dog("바둑이");
dog.makeSound();

다중 구현

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface Flyable {
    fly(): void;
}
interface Swimmable {
    swim(): void;
}
class Duck implements Flyable, Swimmable {
    fly() {
        console.log("날아간다!");
    }
    
    swim() {
        console.log("수영한다!");
    }
}
const duck = new Duck();
duck.fly();
duck.swim();

7. Interface vs Type Alias

비교

특징InterfaceType Alias
객체 타입✅✅
Union/Intersection❌✅
확장extends&
병합✅❌
원시 타입❌✅

예제

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

// Interface
interface User {
    name: string;
}
interface User {
    age: number;
}
// Type Alias
type Person = {
    name: string;
};
// Type Alias는 Union 가능
type ID = string | number;
type Status = "active" | "inactive";
// Intersection
type Employee = Person & {
    employeeId: string;
};

8. 실전 예제

예제 1: API 응답

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며, 비동기 처리를 통해 효율적으로 작업을 수행합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface ApiResponse<T> {
    success: boolean;
    data: T;
    error?: string;
    timestamp: Date;
}
interface User {
    id: string;
    name: string;
    email: string;
}
async function fetchUser(id: string): Promise<ApiResponse<User>> {
    try {
        const response = await fetch(`/api/users/${id}`);
        const data = await response.json();
        return {
            success: true,
            data,
            timestamp: new Date()
        };
    } catch (error) {
        return {
            success: false,
            data: null as any,
            error: "에러 발생",
            timestamp: new Date()
        };
    }
}

예제 2: 폼 검증

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며, 함수를 통해 로직을 구현합니다, 에러 처리를 통해 안정성을 확보합니다. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface FormField {
    value: string;
    error: string | null;
    touched: boolean;
}
interface LoginForm {
    email: FormField;
    password: FormField;
}
const form: LoginForm = {
    email: {
        value: "",
        error: null,
        touched: false
    },
    password: {
        value: "",
        error: null,
        touched: false
    }
};
function validateEmail(email: string): string | null {
    const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
    return regex.test(email) ? null : "올바른 이메일 형식이 아닙니다";
}
form.email.value = "hong@test.com";
form.email.error = validateEmail(form.email.value);
form.email.touched = true;

예제 3: 이벤트 핸들러

다음은 typescript를 활용한 상세한 구현 코드입니다. 클래스를 정의하여 데이터와 기능을 캡슐화하며. 각 부분의 역할을 이해하면서 코드를 살펴보시기 바랍니다.

interface ClickEvent {
    x: number;
    y: number;
    button: "left" | "right";
}
interface EventHandler<T> {
    (event: T): void;
}
const handleClick: EventHandler<ClickEvent> = (event) => {
    console.log(`클릭: (${event.x}, ${event.y}), 버튼: ${event.button}`);
};
handleClick({ x: 100, y: 200, button: "left" });

정리

핵심 요약

  1. Interface: 객체 구조 정의
  2. 선택적 프로퍼티: ?
  3. 읽기 전용: readonly
  4. 확장: extends (다중 가능)
  5. 구현: implements (다중 가능)
  6. 병합: Declaration Merging

Interface 사용 시기

  • 객체 타입 정의
  • 클래스 구조 강제
  • 라이브러리 확장
  • API 응답 타입

다음 단계

관련 글

... 996 lines not shown ... Token usage: 63706/1000000; 936294 remaining Start-Sleep -Seconds 3