nuxt-openfeature-unleash 使用教程

本模块在 Nuxt 3 中集成 Unleash 功能开关，基于 OpenFeature 规范，在服务端使用 Unleash Server SDK，在客户端使用 Unleash Web（Proxy）Provider，通过统一的 useFeature() 在页面或接口中按环境自动选用。

一、安装

在现有 Nuxt 3 项目中安装：

npm install nuxt-openfeature-unleash
# 或
pnpm add nuxt-openfeature-unleash
yarn add nuxt-openfeature-unleash

二、配置

在项目根目录的 nuxt.config.ts 中启用模块并填写 Unleash 配置。

2.1 基本配置

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['nuxt-openfeature-unleash'],

  unleash: {
    // 浏览器端：走 Unleash Frontend API / Proxy，暴露在 runtimeConfig.public.unleash
    client: {
      url: 'https://your-unleash-host/api/frontend/',
      clientKey: 'your-frontend-api-token',
      appName: 'my-app-client',
    },
    // 服务端 / SSR：走 Unleash Core API，仅存在于 runtimeConfig.unleash（不暴露到前端）
    server: {
      url: 'https://your-unleash-host/api/',
      clientKey: 'your-server-api-token',
      appName: 'my-app-server',
    },
  },
})

2.2 配置项说明

| 字段 | 说明 | |------|------| | unleash.client | 客户端（浏览器）配置，对应 Unleash Frontend/Proxy API，会出现在 useRuntimeConfig().public.unleash | | unleash.server | 服务端配置，对应 Unleash Core API，仅存在于 useRuntimeConfig().unleash | | client.url / server.url | Unleash API 基础地址（如 http://localhost:4242/api/frontend/ 或 /api/） | | client.clientKey / server.clientKey | API 密钥 / token | | client.appName / server.appName | 应用名称，用于 Unleash 识别客户端 |

客户端还支持 refreshInterval、disableRefresh 等可选字段，与 unleash-proxy-client 配置兼容。

三、在页面或组件中使用

模块会自动注入 composable useFeature()，无需手动 import。在任意页面或组件的 <script setup> 中可直接使用。

3.1 获取 OpenFeature 客户端

<script setup lang="ts">
const { client, OpenFeature } = await useFeature()
</script>

• 服务端（SSR）：内部使用 Unleash Server + OpenFeature，client 为服务端 Client。
• 客户端（浏览器）：内部使用 Unleash Web Provider，client 为浏览器端 Client。

同一段代码在服务端渲染和客户端 hydration 时会分别使用对应实现。

3.2 读取布尔开关

<script setup lang="ts">
const { client } = await useFeature()

const enabled = await client.getBooleanValue('my-feature-key', false)
</script>

<template>
  <div v-if="enabled">新功能已开启</div>
</template>

• 第一个参数：Unleash 中的 flag 名称（如 my-feature-key）。
• 第二个参数：默认值，当无法连接 Unleash 或未配置该 flag 时使用。

3.3 读取字符串 / 数字 / 对象

const { client } = await useFeature()

const theme = await client.getStringValue('theme-variant', 'light')
const limit = await client.getNumberValue('list-page-size', 10)
const config = await client.getObjectValue('feature-config', {})

3.4 设置评估上下文（用于定向）

Unleash 可根据用户、会话等做定向。通过 OpenFeature 的 setContext 传入：

const { client, OpenFeature } = await useFeature()

await OpenFeature.setContext({
  userId: 'user-123',
  sessionId: 'session-abc',
  // 其他自定义属性
})

const enabled = await client.getBooleanValue('premium-only', false)

在服务端可根据请求信息（如 cookie、header）设置 sessionId 等；在客户端可在用户登录后设置 userId。

3.5 完整示例（页面内）

<template>
  <div>
    <h1>功能开关示例</h1>
    <p v-if="showNewUI">新 UI 已开启</p>
    <button @click="checkFlag">检查开关</button>
  </div>
</template>

<script setup lang="ts">
const { client, OpenFeature } = await useFeature()

const showNewUI = ref(false)

onMounted(async () => {
  await OpenFeature.setContext({ sessionId: 'your-session-id' })
  showNewUI.value = await client.getBooleanValue('new-ui', false)
})

const checkFlag = async () => {
  const enabled = await client.getBooleanValue('new-ui', false)
  console.log('new-ui enabled:', enabled)
}
</script>

四、在服务端 API 中使用

若在 Nitro 的 server API（如 server/api/xxx.ts）里需要做功能开关判断，需要在能拿到 Nuxt 上下文的地方先取 runtimeConfig，再调用服务端逻辑；本模块的 useFeature() 设计为在「Nuxt 上下文内」使用（如 composable、插件、中间件、Vue setup）。

因此推荐做法是：

1. 在 API 的 handler 内部通过事件上下文拿到 runtimeConfig（若框架有注入），再构造与 getUnleashServer(config.unleash, sessionId) 所需的参数一致的对象，调用服务端逻辑；
2. 或者把「是否启用某功能」的逻辑封装在一个 composable 里，在会经过 SSR 的页面中调用该 composable，这样服务端渲染时会在 Nuxt 上下文中执行，可安全使用 useFeature()。

避免在纯 Nitro、无 Nuxt 上下文的代码路径里直接调用 useRuntimeConfig() 或依赖 Nuxt 的 composable，否则会报 “composable was called outside of a plugin...” 类错误。

五、类型说明

• useFeature() 返回：Promise<{ client: Client; OpenFeature: OpenFeatureAPI }>
  • client：OpenFeature 的 Client，支持 getBooleanValue、getStringValue、getNumberValue、getObjectValue 等。
  • OpenFeature：用于 setContext、getContext 等全局 API。
• 服务端 client 的上述方法返回 Promise；客户端为同步，但统一使用 await 即可兼容。

六、常见问题

Q: 客户端报 “composable was called outside of a plugin...”
A: 不要在「无 Nuxt 上下文」的环境（如纯 Nitro 回调、定时器、未在 setup/插件中调用的函数）里调用 useFeature() 或 useRuntimeConfig()。应在 Vue 的 setup、插件、或中间件中调用。

Q: 如何区分「未配置」和「明确关闭」？
A: 使用 client.getBooleanDetails('flag', false) 等 *Details 方法，查看返回的 reason 等字段；未配置或错误时一般为 DISABLED 或 ERROR。

Q: 配置可以只用 client 或只用 server 吗？
A: 可以。只配 client 时仅浏览器端可用；只配 server 时仅服务端/SSR 可用。两边都配则可在同一套代码里自动按环境切换。

七、本地开发与调试

# 安装依赖
npm install

# 生成类型
npm run dev:prepare

# 启动 playground
npm run dev

在 playground/nuxt.config.ts 和 playground/pages/index.vue 中有完整配置与调用示例，可对照本教程修改和试验。