npm package: @lark-apaas/express-core
Description: Express core framework with platform middleware integration
Latest version: 0.0.9

# @lark-apaas/express-core

Express 技术栈的平台核心框架，通过 `setup()` 一次性注册所有平台中间件，将平台逻辑与业务逻辑在框架层解耦。

## 功能特性

- 自动注册平台中间件链（UserContext、CSRF、RLS、ViewContext）
- 集成 DataPaaS 数据库连接管理与 RLS 支持
- CSRF Token 生成与验证
- 应用元数据自动注入到模板渲染上下文
- ESM live binding 导出 `db` 实例，使用体验与社区一致

## 安装

```bash
npm install @lark-apaas/express-core
```

### Peer Dependencies

```bash
npm install drizzle-orm@0.44.6 express
```

## 快速开始

### 1. 初始化应用

```typescript
// app.ts
import express from 'express';
import { setup } from '@lark-apaas/express-core';

const app = express();
const { close } = setup(app);

// 业务路由
app.get('/api/users', async (req, res) => { ... });

app.listen(3000);
process.on('SIGTERM', () => close());
```

### 2. 使用数据库

```typescript
// routes/users.ts
import { db } from '@lark-apaas/express-core';
import { users } from '../schema';

router.get('/users', async (req, res) => {
  const result = await db.select().from(users);
  res.json(result);
});
```

### 3. 访问用户上下文

```typescript
app.get('/api/profile', (req, res) => {
  const { userId, tenantId, roles } = req.userContext;
  res.json({ userId, tenantId, roles });
});
```

### 4. 访问平台数据（模板渲染）

```typescript
app.get('/', (req, res) => {
  // res.locals 已自动注入 appName, csrfToken 等
  res.render('index');
});
```

## API 参考

### setup(app, config?)

初始化 Express 应用，注册所有平台中间件。

**参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| `app` | `express.Application` | Express 实例 |
| `config` | `SetupConfig` | 可选配置 |

**返回值：** `{ close: () => Promise<void> }` — 用于优雅关闭数据库连接。

**SetupConfig：**

| 字段 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `database.connectionString` | `string` | `process.env.DATABASE_URL` | PostgreSQL 连接串 |
| `database.schema` | `object` | - | Drizzle schema |
| `database.maxConnections` | `number` | `1` | 最大连接数 |
| `csrf.enabled` | `boolean` | `true` | 是否启用 CSRF 保护 |
| `csrf.cookieKey` | `string` | `'suda-csrf-token'` | CSRF cookie 名称 |
| `csrf.headerKey` | `string` | `'x-suda-csrf-token'` | CSRF header 名称 |
| `csrf.routes` | `string[]` | `['/api/*']` | CSRF 验证路由 |
| `bodyLimit` | `string` | `'1mb'` | body parser 大小限制 |

### db

通过 ESM live binding 导出的 Drizzle 数据库实例。`setup()` 调用后可用。

```typescript
import { db } from '@lark-apaas/express-core';
```

### 中间件（高级用法）

各中间件也单独导出，供高级用户自行组合：

```typescript
import {
  userContextMiddleware,
  createCsrfTokenMiddleware,
  createCsrfValidationMiddleware,
  createViewContextMiddleware,
} from '@lark-apaas/express-core';
```

## setup() 注册的中间件顺序

| 顺序 | 中间件 | 作用域 | 说明 |
|------|--------|--------|------|
| 1 | body parser | 所有路由 | JSON + URL-encoded 解析 |
| 2 | cookie-parser | 所有路由 | Cookie 解析 |
| 3 | userContextMiddleware | 所有路由 | 从请求头解析用户上下文 |
| 4 | DataPaaS + RLS | 所有路由 | 数据库连接 + 行级安全 |
| 5 | csrfTokenMiddleware | 所有路由 | 生成 CSRF Token |
| 6 | csrfValidationMiddleware | `/api/*` | 验证 CSRF Token |
| 7 | viewContextMiddleware | 所有路由 | 注入应用元数据到渲染上下文 |

## req 扩展字段

| 字段 | 类型 | 来源 |
|------|------|------|
| `req.userContext` | `UserContext` | userContextMiddleware |
| `req.csrfToken` | `string` | csrfTokenMiddleware |
| `req.__platform_data__` | `object` | viewContextMiddleware |

## 注意事项

1. `setup()` 必须在注册业务路由之前调用
2. `db` 在 `setup()` 调用前为 `undefined`
3. 不传 `database.connectionString` 时自动读取 `process.env.DATABASE_URL`
4. drizzle-orm 必须为 `0.44.6` 版本

## License

MIT