[스트라피 공식 문서 번역] Route

Routes

스트라피로 전송되는 모든 URL은 라우트에 의해 핸들링 됩니다. 스트라피는 필요한 content types에 대한 모든 라우트를 자동적으로 생성합니다. 라우트는 추가될 수도, 설정될 수도 있습니다.

• 정책(policies)를 사용하면 라우트에 대한 접근을 차단할 수 있습니다.
• 미들웨어(middlewares)를 사용하면 요청의 흐름 혹은 요청 그 자체를 조작하고 바꿀 수 있습니다.

요청이 라우트에 도착하면, 컨트롤러에 의해 작동되는 코드가 실행됩니다.

 

구현하기

새로운 라우트를 구현하는 것은 ./src/api/[api-name]/routes 폴더 내의 라우트 파일을 정의하는 것으로 구성됩니다.

라우트 파일 구조는 용례에 따라 2가지 형태로 존재합니다.

• 핵심 라우터(core routers)를 구성하는 것
• 사용자 라우터(custom routers)를 생성하는 것

 

핵심 라우터 구성하기

find, findOne, create, update, delete와 같은 핵심 라우터들은 새로운 content type이 생성될 때 자동으로 생성되는 라우트입니다.

스트라피가 제공하는 createCoreRouter 팩토리 함수는 자동으로 핵심 라우터를 생성하고 아래와 같은 기능을 제공합니다.

• 각 라우터에 구성 옵션(configuration options)을 전달
• 사용자 라우터 생성을 위해 몇몇 핵심 라우터를 비활성화

핵심 라우터 파일은 아래의 매개변수를 사용해 createCoreRoute의 호출 결과를 출력하는 자바스크립트 파일입니다.

매개변수	설명	자료형
prefix	이 모델을 위한 모든 라우터에 추가할 사용자 지정 접두사(prefix)를 전달할 수 있습니다. (ex. /test)	String
only	불러질 수 있는 핵심 라우트들 이 배열에 존재하지 않는 모든 것은 무시됩니다.	Array
except	불러지면 안되는 핵심 라우트들 except는 기능적으로 only와 완전히 반대되는 매개변수입니다.	Array
config	라우트를 위한 정책(policies), 미들웨어, public availability를 다루기 위한 설정	Object

 

// path: ./src/api/[apiName]/routes/[routerName].js (e.g './src/api/restaurant/routes/restaurant.js')

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
	prefix: '',
	only: ['find', 'findOne'],
	except: [],
	config: {
		find: {
			auth: false,
			policies: [],
			middlewares: [],
		},
		findOne: {},
		create: {},
		update: {},
		delete: {},
	}
});

// 일반화 프로그래밍(Generic implementation) 예시
// path: ./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
	only: ['find'],
	config: {
		find: {
			auth: false,
			policies: [],
			middlewares: [],
		}
	}
});

위의 코드는 인증하지 않은 사용자가 /restaurant 경로에 접근했을 때 핵심 find 컨트롤러에 대한 GET 요청만을 허락한다는 의미를 담고 있습니다.

 

사용자 지정 라우터 생성하기

사용자 지정 라우터를 생성하는 것은 객체의 배열을 내보내는 파일을 생성하는 것으로 각각의 객체는 아래의 매개변수로 라우트 됩니다. (Creating custom routers consists in creating a file that exports an array of objects, each object being a route with the following parameters:)

매개변수	설명	자료형
method	라우트와 관련된 메소드 (ex. GET, POST, PUT, DELETE, PATCH)	String
path	도달하고자 하는 위치. 앞에 / 를 작성함으로써 사용합니다. (ex. /articles)	String
handler	경로에 도달했을 때 실행할 함수입니다. <controllerName>.<actionName>의 문법을 따라야 합니다.	String
config (선택사항)	라우트를 위한 정책(policies), 미들웨어, public availability를 다루기 위한 설정	Object

동적 라우트는 매개변수와 정규표현식을 이용해 생성할 수 있습니다. 이러한 매개변수는 ctx.params 객체에서 획득 가능합니다. 보다 더 자세한 부분이 궁금하시다면 PathToRegex 문서를 참고하시기 바랍니다.

// URL 매개변수와 정규표현식을 사용한 사용자 지정 라우터의 예
// path: ./src/api/restaurant/routes/custom-restaurant.js

module.exports = {
	routes: [
		{ // URL 매개변수로 정의된 경로
			method: 'GET',
			path: '/restaurants/:category/:id',
			handler: 'Restaurant.findOneByCategory',
		},
		{ // 정규 표현식으로 정의된 경로
			method: 'GET',
			path: '/restaurants/:region(\\\\d{2}|\\\\d{3})/:id, 
			handler: 'Restaurant.findOneByRegion',
		}
	]
}

 

구성하기

핵심 라우터와 사용자 지정 라우터 모두 동일한 설정 옵션이 존재합니다. 라우트에 대한 설정은 정책(policies), 미들웨어를 핸들하거나 라우트를 공개하는데 사용될 수 있는 config 객체에 의해 정의됩니다.

 

정책(policies)

정책은 라우트 설정에서 추가할 수 있습니다.

• 사용자 정의된 설정을 지나치거나 지나치지 않고 ./src/policies에 등록된 정책을 가리킴(by pointing)으로써 라우트 설정에 추가할 수 있습니다.
• Koa’s context(ctx)와 매개변수인 strapi 인스턴스를 확장한 policyContext를 사용하는 함수를 직접적으로 구현해 선언함으로써 라우트 설정에 추가할 수 있습니다. (or by declaring the policy implementation directly, as a function that takes policyContext to extend Koa's context (opens new window)(ctx) and the strapi instance as arguments)

// 핵심 라우터 정책
// path: ./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
	config: {
		find: {
			policies: [
				// 등록된 정책을 가리킨다.
				'policy-name',
		
				// 사용자 지정 설정이 들어간 등록된 정책을 가리킨다.
				{ name: 'policy-name', config: {} },

				// 정책 구현을 지나친다.
				(policyContext, config, { strapi }) => {
					return true;
				}
			]
		}
	]
});

// 사용자 지정 라우터 정책
// path: ./src/api/restaurant/routes/custom-restaurant.js

module.exports = {
	routes: [
		{
			method: 'GET',
			path: '/articles/customRoute',
			handler: 'controllerName.actionName',
			config: {
				policies: [
					// 등록된 정책을 가리킨다.
					'policy-name',

					// 사용자 지정 설정이 들어간 등록된 정책을 가리킨다.
					{ name: 'policy-name', config: {} },

					// 정책 구현을 지나친다.
					(policyContext, config, { strapi }) => {
						return true;
					},
				]
			},
		},
	],
};

 

미들웨어

미들웨어는 라우트 설정에서 추가할 수 있습니다.

• 사용자 정의된 설정을 지나치거나 지나치지 않고 ./src/middlewares에 등록된 정책을 가리킴(by pointing)으로써 라우트 설정에 추가할 수 있습니다.
• Koa’s context(ctx)와 매개변수인 strapi 인스턴스를 사용하는 함수를 직접적으로 구현해 선언함으로써 미들웨어 설정에 추가할 수 있습니다.

// 핵심 라우터 미들웨어
// path: ./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
	config: {
		find: {
			middlewares: [
				// 등록된 미들웨어를 가리킨다.
				'middleware-name',

				// 사용자 지정 설정이 들어간 등록된 미들웨어를 가리킨다.
				{ name: 'middleware-name', config: {} },

				// 미들웨어 구현을 지나친다.
				(ctx, next) => {
					return next();
				},
			]
		}
	}
});

// 사용자 지정 라우터 미들웨어
// path: ./src/api/restaurant/routes/custom-restaurant.js

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles/customRoute',
      handler: 'controllerName.actionName',
      config: {
        middlewares: [
          // 등록된 미들웨어를 가리킨다.
          'middleware-name', 

          // 사용자 지정 설정이 들어간 등록된 미들웨어를 가리킨다.
          { name: 'middleware-name', config: {} }, 

          // 미들웨어 구현을 지나친다.
          (ctx, next) => {
            return next();
          },
        ],
      },
    },
  ],
};

 

Public routes

라우트는 기본적으로 API 토근 혹은 사용자 & 승인 플러그인(Users & Permissions plugin)에 기반을 둔 스트라피 인증 시스템에 의해 보호됩니다.

일부 시나리오에서는 라우트를 공개적으로 사용하고 일반 스트라피 인증 시스템 외부에서 엑세스를 제어하는 것이 유용할 수 있습니다. 이러한 작업은 auth 설정 매개변수를 false로 설정함으로써 가능합니다.

// public 처리된 핵심 라우터
// path: ./src/api/restaurant/routes/restaurant.js

const { createCoreRouter } = require('@strapi/strapi').factories;

module.exports = createCoreRouter('api::restaurant.restaurant', {
  config: {
    find: {
      auth: false
    }
  }
});

// public 처리된 사용자 지정 라우터
// path: ./src/api/restaurant/routes/custom-restaurant.js

module.exports = {
  routes: [
    {
      method: 'GET',
      path: '/articles/customRoute',
      handler: 'controllerName.actionName',
      config: {
        auth: false,
      },
    },
  ],
};