初始化 Koa2 项目的步骤

环境准备

首先确保系统已安装 Node.js 和 npm/yarn。推荐使用 Node.js 12.x 或更高版本，可以通过以下命令检查版本：

node -v
npm -v

建议使用 nvm 管理 Node.js 版本，便于切换不同项目所需的 Node 版本：

nvm install 14
nvm use 14

创建项目目录

新建项目文件夹并初始化 package.json：

mkdir koa2-demo
cd koa2-demo
npm init -y

建议手动修改生成的 package.json，添加必要的描述信息和作者等字段。示例：

{
  "name": "koa2-demo",
  "version": "1.0.0",
  "description": "A demo Koa2 project",
  "main": "app.js",
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon app.js"
  }
}

安装 Koa2 核心依赖

安装 Koa 本体和常用中间件：

npm install koa koa-router koa-bodyparser

如果需要 TypeScript 支持，还需安装类型声明：

npm install @types/koa @types/koa-router --save-dev

基础应用结构

创建 app.js 作为入口文件，基础结构如下：

const Koa = require('koa')
const app = new Koa()

// 响应时间中间件
app.use(async (ctx, next) => {
  const start = Date.now()
  await next()
  const ms = Date.now() - start
  ctx.set('X-Response-Time', `${ms}ms`)
})

// 响应
app.use(async ctx => {
  ctx.body = 'Hello Koa'
})

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000')
})

路由配置

使用 koa-router 创建路由模块。新建 routes/index.js：

const Router = require('koa-router')
const router = new Router()

router.get('/', async (ctx) => {
  ctx.body = { message: 'Home Page' }
})

router.get('/users', async (ctx) => {
  ctx.body = [
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' }
  ]
})

module.exports = router

在 app.js 中引入路由：

const router = require('./routes')
app.use(router.routes()).use(router.allowedMethods())

中间件集成

常用中间件配置示例：

const bodyParser = require('koa-bodyparser')
const cors = require('@koa/cors')

// 解析请求体
app.use(bodyParser({
  enableTypes: ['json', 'form'],
  formLimit: '10mb'
}))

// 跨域支持
app.use(cors({
  origin: '*',
  allowMethods: ['GET', 'POST', 'PUT', 'DELETE']
}))

// 错误处理
app.use(async (ctx, next) => {
  try {
    await next()
  } catch (err) {
    ctx.status = err.status || 500
    ctx.body = { error: err.message }
    ctx.app.emit('error', err, ctx)
  }
})

配置文件管理

使用 dotenv 管理环境变量。安装依赖：

npm install dotenv

创建 .env 文件：

PORT=3000
DB_HOST=localhost
DB_PORT=27017

在 app.js 顶部加载配置：

require('dotenv').config()
const PORT = process.env.PORT || 3000

日志记录

推荐使用 koa-logger 中间件：

npm install koa-logger

集成到应用中：

const logger = require('koa-logger')
app.use(logger())

自定义日志格式示例：

app.use(async (ctx, next) => {
  const start = new Date()
  await next()
  const ms = new Date() - start
  console.log(`${ctx.method} ${ctx.url} - ${ms}ms`)
})

静态文件服务

使用 koa-static 提供静态资源：

npm install koa-static

配置示例：

const serve = require('koa-static')
const path = require('path')

app.use(serve(path.join(__dirname, 'public'), {
  maxage: 365 * 24 * 60 * 60 * 1000 // 缓存一年
}))

数据库连接

以 MongoDB 为例，使用 mongoose：

npm install mongoose

创建 db.js 连接文件：

const mongoose = require('mongoose')

const connectDB = async () => {
  try {
    await mongoose.connect(process.env.DB_URI, {
      useNewUrlParser: true,
      useUnifiedTopology: true
    })
    console.log('MongoDB Connected...')
  } catch (err) {
    console.error(err.message)
    process.exit(1)
  }
}

module.exports = connectDB

在 app.js 中调用：

const connectDB = require('./db')
connectDB()

项目结构优化

推荐的项目目录结构：

├── app.js
├── config/
│   └── index.js
├── controllers/
│   └── userController.js
├── models/
│   └── User.js
├── middlewares/
│   └── auth.js
├── routes/
│   ├── index.js
│   └── api/
│       ├── user.js
│       └── product.js
├── public/
│   ├── images/
│   └── styles/
└── utils/
    └── logger.js

开发工具配置

安装 nodemon 实现热重载：

npm install nodemon --save-dev

修改 package.json 的 scripts：

{
  "scripts": {
    "start": "node app.js",
    "dev": "nodemon --watch '**/*.js' --exec node app.js",
    "test": "jest"
  }
}

添加 .gitignore 文件：

node_modules/
.env
.DS_Store
logs/
*.log

测试环境搭建

使用 Jest 进行单元测试：

npm install jest supertest --save-dev

创建测试文件 tests/app.test.js：

const request = require('supertest')
const app = require('../app')

describe('GET /', () => {
  it('should return 200 OK', async () => {
    const res = await request(app.callback()).get('/')
    expect(res.status).toBe(200)
  })
})

部署准备

添加 PM2 配置文件 ecosystem.config.js：

module.exports = {
  apps: [{
    name: 'koa-app',
    script: 'app.js',
    instances: 'max',
    autorestart: true,
    watch: false,
    max_memory_restart: '1G',
    env: {
      NODE_ENV: 'production',
      PORT: 3000
    }
  }]
}

性能优化

启用 gzip 压缩：

npm install koa-compress

配置示例：

const compress = require('koa-compress')

app.use(compress({
  threshold: 2048,
  gzip: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  deflate: {
    flush: require('zlib').constants.Z_SYNC_FLUSH
  },
  br: false
}))

安全加固

常用安全中间件：

npm install koa-helmet koa-rate-limit

配置示例：

const helmet = require('koa-helmet')
const rateLimit = require('koa-rate-limit')

app.use(helmet())
app.use(rateLimit({
  interval: { min: 15 }, // 15分钟
  max: 100 // 每个IP最多100请求
}))

错误监控

集成 Sentry 进行错误跟踪：

npm install @sentry/node

配置示例：

const Sentry = require('@sentry/node')

Sentry.init({
  dsn: process.env.SENTRY_DSN,
  tracesSampleRate: 1.0
})

app.on('error', (err, ctx) => {
  Sentry.captureException(err)
})