[내보내번] Next.js docs - API Middlewares

내보내번(내가 보려고 내가 번역한...) Next.js docs

2021년 4월 15일 기준 Next.js 공식 문서를 번역했다.

※ 영어 전공자도 해외 유학파도 아니기에 번역에는 의역, 오역, 구글 번역이 무수히 많을 수 있으며, 혼자 공식문서를 참조해가며 번역하다 보니 오타도 많을 수 있다. 정확한 내용은 공식문서를 직접 살펴보거나 다른 정보들을 더 찾아보는 것을 추천한다.

(하지만 댓글 피드백도 환영합니다😃 )

Next.js 공식문서 확인하기>>

API Routes: API Middlewares | Next.js

---

API routes provide built in middlewares which parse the incoming request (req). Those middlewares are:
API 라우트는 받은 요청(req)을 구문 분석하는 내장 미들웨어를 제공한다. 미들웨어에는: 

• req.cookies - An object containing the cookies sent by the request. Defaults to {}
• req.query - An object containing the query string. Defaults to {}
• req.body - An object containing the body parsed by content-type, or null if no body was sent
• req.cookes - 요청에 의해 전달받은 쿠키를 포함하는 객체. 기본값은 {}
• req.query - 쿼리 스트링을 포함하는 객체. 기본값은 {}
• req.body - content-type으로 구문 분석된 body 혹은 전송된 body가 없는 경우는 null을 포함하는 객체

Custom config

Every API route can export a config object to change the default configs, which are the following:
모든 API 라우트는 기본 config를 변경하기 위해서 config 객체를 내보낼 수 있는데 다음과 같다:

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '1mb',
    },
  },
}

The api object includes all configs available for API routes.
api 객체는 API 라우트에 사용가능한 모든 구성을 포함한다. 

'bodyParser' Enables body parsing, you can disable it if you want to consume it as a Stream:
bodyParse는 body 구문 분석을 활성화하고 Stream으로 사용하고 싶으면 비활성화하면 된다:

export const config = {
  api: {
    bodyParser: false,
  },
}

bodyParser.sizeLimit is the maximum size allowed for the parsed body, in any format supported by bytes, like so:
bodyParser.sizeLimit은 구문 분석된 body의 허용되는 최대 크기에 대한 것으로 bytes에서 지원하는 어떤 형식도 가능하다:

export const config = {
  api: {
    bodyParser: {
      sizeLimit: '500kb',
    },
  },
}

externalResolver is an explicit flag that tells the server that this route is being handled by an external resolver like express or connect. Enabling this option disables warnings for unresolved requests.
externalResolver는 이 라우트는 express, connect 같은 외부 resolver에 의해 처리된다는 것을 서버에 알려주기 위한 명시적인 플래그이다. 이 옵션을 활성화하면 해결되지 않은 요청에 대한 경고는 비활성화된다. 

export const config = {
  api: {
    externalResolver: true,
  },
}

 

Connect/Express middleware support

You can also use Connect compatible middleware.
Connect 호환 미들웨어도 사용할 수 있다. 

For example, configuring CORS for your API endpoint can be done leveraging the cors package.
예를 들면, API 엔드포인트에 대한 CORS 구성은 cors 패키지를 활용함으로 수행될 수 있다. 

First, install cors:
먼저 cors를 설치한다:

npm i cors
# or
yarn add cors

Now, let's add cors to the API route:
이제 API 라우트에 cors를 추가하자:

import Cors from 'cors'

// Initializing the cors middleware
const cors = Cors({
  methods: ['GET', 'HEAD'],
})

// Helper method to wait for a middleware to execute before continuing
// And to throw an error when an error happens in a middleware
function runMiddleware(req, res, fn) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result) => {
      if (result instanceof Error) {
        return reject(result)
      }

      return resolve(result)
    })
  })
}

async function handler(req, res) {
  // Run the middleware
  await runMiddleware(req, res, cors)

  // Rest of the API logic
  res.json({ message: 'Hello Everyone!' })
}

export default handler

Go to the API Routes with CORS example to see the finished app
API Routes with CORS 예제에서 완성된 앱을 확인할 수 있다. 

 

Extending the req/res objects with TypeScript

For better type-safety, it is not recommended to extend the req and res objects. Instead, use pure functions to work with them:
더 나은 타입 안정성을 위해서 req와 res 객체를 확장하는 것은 권장하지 않는다. 대신 순수 함수를 사용하여 확장할 수 있다. 

// utils/cookies.ts

import { serialize, CookieSerializeOptions } from 'cookie'
import { NextApiResponse } from 'next'

/**
 * This sets `cookie` using the `res` object
 */

export const setCookie = (
  res: NextApiResponse,
  name: string,
  value: unknown,
  options: CookieSerializeOptions = {}
) => {
  const stringValue =
    typeof value === 'object' ? 'j:' + JSON.stringify(value) : String(value)

  if ('maxAge' in options) {
    options.expires = new Date(Date.now() + options.maxAge)
    options.maxAge /= 1000
  }

  res.setHeader('Set-Cookie', serialize(name, String(stringValue), options))
}

// pages/api/cookies.ts

import { NextApiRequest, NextApiResponse } from 'next'
import { setCookie } from '../../utils/cookies'

const handler = (req: NextApiRequest, res: NextApiResponse) => {
  // Calling our pure function using the `res` object, it will add the `set-cookie` header
  setCookie(res, 'Next.js', 'api-middleware!')
  // Return the `set-cookie` header so we can display it in the browser and show that it works!
  res.end(res.getHeader('Set-Cookie'))
}

export default handler

If you can't avoid these objects from being extended, you have to create your own type to include the extra properties:
객체를 확장할 수 밖에 없다면, 추가적인 속성들을 포함하기 위해서 자신만의 타입을 생성해야 한다. 

// pages/api/foo.ts

import { NextApiRequest, NextApiResponse } from 'next'
import { withFoo } from 'external-lib-foo'

type NextApiRequestWithFoo = NextApiRequest & {
  foo: (bar: string) => void
}

const handler = (req: NextApiRequestWithFoo, res: NextApiResponse) => {
  req.foo('bar') // we can now use `req.foo` without type errors
  res.end('ok')
}

export default withFoo(handler)

Keep in mind this is not safe since the code will still compile even if you remove withFoo() from the export.
withFoo()를 내보내기에서 제거해도 여전히 컴파일되기 때문에 안전하기 않다는 것을 기억하라.