디스코드 봇 명령어, 길드 커맨드와 글로벌 커맨드 차이점, 사용 방법

소개

Discord.js v13부터 슬래시 커맨드(Slash Commands)가 정식으로 도입되었습니다. 슬래시 커맨드는 사용자가 채팅창에 '/'를 입력하면 나타나는 명령어들로, Discord API를 통해 등록하고 관리할 수 있습니다. 이전 Discord.js 버전에서는 메시지 기반의 명령어가 주로 사용되었지만, Message Contant Intent가 필요한다는 점과 리소스 소모가 크다는 단점 때문에 슬래시 커맨드가 더 선호되고 있습니다.

Global Commands

Global Commands는 봇이 접근할 수 있는 모든 서버(길드)에서 사용 가능한 슬래시 커맨드입니다.
봇이 초대된 모든 서버에서 사용할 수 있는 명령어로, 한 번 등록하면 모든 서버에 적용됩니다.

장점

• 한 번 등록으로 모든 서버에 적용됨
  이 부분은 discord API의 rate limit와 관련되어 있습니다. 이후 설명드릴 Guild Commands로 명령어를 배포하게 되면, 각 서버마다 별도로 등록해야 하기 때문에 Discord API의 rate limit에 걸릴 수 있습니다.
• 중앙 집중식 관리가 가능
• 봇 사용자에게 일관된 경험 제공

단점

• 변경사항이 반영되는 데 시간이 오래 걸림 -> 테스트 시에는 불편함이 존재합니다.
  Discord API의 캐싱 메커니즘으로 인해, 명령어 등록 후 최대 1시간까지 반영되지 않을 수 있습니다.
• 특정 서버에 맞춤형 명령어를 제공하기 어려움

Guild Commands

Guild Commands는 특정 서버(길드)에서만 사용 가능한 슬래시 커맨드입니다.
이 명령어는 봇이 초대된 특정 서버에만 적용되며, 각 서버마다 별도로 등록해야 합니다.
Guild Commands는 개발 및 테스트 환경에서 주로 사용되며, 서버별로 맞춤형 명령어를 제공할 수 있습니다.

장점

• 변경사항이 즉시 반영됨
  이후 설명드릴 코드를 통해 특정 길드에 명령어를 등록하면, 해당 길드에서 즉시 사용할 수 있습니다.
• 개발 중 빠른 테스트 가능
  Discord API의 캐싱과 관계없이 바로 적용됩니다.
• 서버별 맞춤형 명령어 제공 가능

단점

• 각 서버마다 별도로 등록해야 함
  이로 인해 앞서 설명드린 Discord API의 rate limit에 걸릴 수 있습니다.
• 많은 서버에서 관리하기 복잡함
• 서버별 다른 명령어 세트로 인한 사용자 혼란 가능성

차이점 비교

특성	Global Commands	Guild Commands
가용성	모든 서버	특정 서버만
업데이트 시간	최대 1시간	즉시
등록 API 경로	/applications/:id/commands	/applications/:id/guilds/:guild_id/commands
적합한 환경	프로덕션	개발/테스트
명령어 수 제한	100개	서버당 100개
봇 퇴장 시	명령어 유지	명령어 제거

코드 예시

Global Commands 등록하기

import { REST, Routes } from "discord.js";
import { config } from "./config";
import { commands } from "./commands";

const commandsData = Object.values(commands).map((command) => command.data);

const rest = new REST({ version: "10" }).setToken(config.DISCORD_TOKEN);

type DeployCommandsProps = {
  guildId?: string; // guildId를 선택적으로 변경
};

export async function deployCommands({ guildId }: DeployCommandsProps = {}) {
  try {
    if (guildId) {
      // 길드별 명령어 배포 (서버별 배포)
      console.log(`길드 ${guildId}에 명령어 배포 중...`);
      await rest.put(
        Routes.applicationGuildCommands(config.DISCORD_CLIENT_ID, guildId),
        {
          body: commandsData,
        }
      );
      console.log(`길드 ${guildId}에 명령어 배포 완료`);
    } else {
      // 글로벌 명령어 배포 (모든 서버에 적용)
      console.log("글로벌 명령어 배포 중...");
      await rest.put(Routes.applicationCommands(config.DISCORD_CLIENT_ID), {
        body: commandsData,
      });
      console.log(
        "글로벌 명령어 배포 완료 (최대 1시간 내에 모든 서버에 적용됨)"
      );
    }
  } catch (error) {
    console.error("명령어 배포 중 오류 발생:", error);
  }
}

Guild Commands 등록하기

import { REST, Routes } from "discord.js";
import { config } from "./config";
import { commands } from "./commands";

const commandsData = Object.values(commands).map((command) => command.data);

const rest = new REST({ version: "10" }).setToken(config.DISCORD_TOKEN);

type DeployCommandsProps = {
  guildId: string;
};

export async function deployCommands({ guildId }: DeployCommandsProps) {
  try {
    await rest.put(
      Routes.applicationGuildCommands(config.DISCORD_CLIENT_ID, guildId),
      {
        body: commandsData,
      }
    );
  } catch (error) {
    console.error(error);
  }
}

명령어 삭제하기

Global Commands 삭제

import { REST, Routes } from "discord.js";
import { config } from "./config";

const rest = new REST({ version: "10" }).setToken(config.DISCORD_TOKEN);

// 모든 글로벌 명령어 삭제
await rest.put(Routes.applicationCommands(config.DISCORD_CLIENT_ID), {
  body: [],
});

// 특정 글로벌 명령어 삭제
await rest.delete(
  Routes.applicationCommand(config.DISCORD_CLIENT_ID, "command_id")
);

Guild Commands 삭제

import { REST, Routes } from "discord.js";
import { config } from "./config";

const rest = new REST({ version: "10" }).setToken(config.DISCORD_TOKEN);

// 특정 서버의 모든 명령어 삭제
await rest.put(
  Routes.applicationGuildCommands(config.DISCORD_CLIENT_ID, "GUILD_ID"),
  { body: [] }
);

// 특정 서버의 특정 명령어 삭제
await rest.delete(
  Routes.applicationGuildCommand(
    config.DISCORD_CLIENT_ID,
    "GUILD_ID",
    "command_id"
  )
);

최적의 사용 사례

Global Commands 사용이 적합한 경우

1. 안정적인 프로덕션 기능
   • 충분히 테스트되고 안정적인 명령어
   • 모든 서버에서 동일하게 동작해야 하는 핵심 기능
2. 기본 명령어
   • /help, /info, /settings와 같은 기본적인 봇 명령어
   • 모든 사용자가 접근해야 하는 일반적인 기능
3. 대규모 봇
   • 많은 서버에 배포되는 대형 봇의 경우 Discord API의 rate limit을 고려하여 Global Commands를 사용하는 것이 효율적입니다.

Guild Commands 사용이 적합한 경우

1. 개발 및 테스트
   • 새로운 기능 개발 중
   • 버그 수정 및 테스트 과정
2. 서버 특화 기능
   • 특정 서버에만 필요한 맞춤형 명령어
   • 특정 서버의 관리 기능
3. 베타 테스트
   • 제한된 사용자 그룹에게만 제공하는 베타 기능

---

참고 자료

• Discord.js 공식 가이드 - 슬래시 커맨드 등록
• Discord 개발자 문서 - 애플리케이션 명령어