技能 编程开发 Glean本地开发与模拟环境

Glean本地开发与模拟环境

v20260423
glean-local-dev-loop
本工具提供一套完整的Glean企业搜索API本地开发工作流。它允许开发者模拟本地搜索结果、数据源和连接器,从而在无需实际Glean部署的情况下开发和测试自定义的搜索界面和数据连接器。支持在模拟模式和沙箱模式之间切换,加速开发迭代,确保构建健壮的企业搜索应用。
获取技能
452 次下载
概览

Glean Local Dev Loop

Overview

Local development workflow for Glean enterprise search API integration. Provides a fast feedback loop with mock search results, connector testing, and document indexing simulation so you can build custom datasource connectors and search UIs without needing a live Glean deployment. Toggle between mock mode for rapid connector iteration and sandbox mode for validating against your Glean instance.

Environment Setup

cp .env.example .env
# Set your credentials:
# GLEAN_API_KEY=glean_xxxxxxxxxxxx
# GLEAN_INSTANCE=https://your-company.glean.com
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express

Dev Server

// src/dev/server.ts
import express from "express";
import { createProxyMiddleware } from "http-proxy-middleware";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) {
  app.use("/api", createProxyMiddleware({
    target: process.env.GLEAN_INSTANCE,
    changeOrigin: true,
    headers: { Authorization: `Bearer ${process.env.GLEAN_API_KEY}` },
  }));
} else {
  const { mountMockRoutes } = require("./mocks");
  mountMockRoutes(app);
}
app.listen(3003, () => console.log(`Glean dev server on :3003 [mock=${MOCK}]`));

Mock Mode

// src/dev/mocks.ts — realistic enterprise search responses
export function mountMockRoutes(app: any) {
  app.post("/api/search", (req: any, res: any) => res.json({
    results: [
      { title: "Q4 Engineering Roadmap", url: "https://wiki.co/roadmap", score: 0.97, datasource: "confluence",
        snippets: [{ snippet: "The <b>roadmap</b> includes migration to..." }] },
      { title: "Onboarding Guide", url: "https://wiki.co/onboard", score: 0.88, datasource: "notion",
        snippets: [{ snippet: "New hire <b>onboarding</b> steps..." }] },
    ],
    totalCount: 2,
  }));
  app.post("/api/index/documents", (req: any, res: any) => res.json({
    status: "OK", documentsIndexed: req.body.documents?.length || 0,
  }));
  app.get("/api/datasources", (_req: any, res: any) => res.json([
    { name: "confluence", displayName: "Confluence", docCount: 1250 },
    { name: "notion", displayName: "Notion", docCount: 430 },
  ]));
}

Testing Workflow

npm run dev:mock &                    # Start mock server in background
npm run test                          # Unit tests with vitest
npm run test -- --watch               # Watch mode for rapid iteration
MOCK_MODE=false npm run test:integration  # Integration test against real Glean instance

Debug Tips

  • Use curl -X POST http://localhost:3003/api/search -d '{"query":"test"}' to verify mock search
  • Glean connectors must return documents with id, title, body.textContent, and datasource fields
  • Check connector transform output shape before pushing to the indexing API
  • Enable verbose logging on the Glean SDK client to trace API call timing
  • Verify OAuth scopes if search returns empty results against a live instance

Error Handling

IssueCauseFix
401 UnauthorizedInvalid API key or expired tokenRegenerate at Glean admin console
403 ForbiddenKey lacks indexing scopeRequest Indexing API permissions from admin
400 Bad RequestMalformed document payloadValidate required fields: id, title, body
429 Rate LimitedToo many indexing requestsBatch documents (max 100 per request)
ECONNREFUSED :3003Dev server not runningRun npm run dev:mock first

Resources

Next Steps

See glean-debug-bundle.

信息
分类 编程开发
名称 glean-local-dev-loop
版本 v20260423
大小 4.19KB
更新时间 2026-04-28
语言