Wix CLI 后端 API 构建器教程 - 创建 HTTP 端点与 REST API

wix-cli-backend-api by wix/skills

251 周安装量

8 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/wix/skills --skill wix-cli-backend-api

Web应用命令行工具 API

🇨🇳中文介绍

Wix 后端 API 构建器

为 Wix CLI 应用程序创建 HTTP 端点 —— 这些是服务器端路由，用于处理 HTTP 请求、处理数据并返回响应。HTTP 端点由 Astro 端点提供支持，并能从文件系统自动发现。

关键信息：

文件位于 src/pages/api/ 目录下，扩展名为 .ts
无法通过 npm run generate 添加 —— 请直接创建文件
不会显示在应用仪表板的扩展页面中
无需扩展注册（自动发现）
取代了旧版 Wix CLI for Apps 中的“HTTP 函数”

使用场景

在以下情况下使用 HTTP 端点：

构建支持多种 HTTP 方法的 REST API
与外部 API 或服务集成
处理复杂的表单提交或文件上传
提供动态内容（图像、RSS 源、个性化数据）
访问运行时数据或服务器端数据库

文件结构与命名

基础端点

文件路径决定了端点 URL：

src/pages/api/<your-endpoint-name>.ts

动态路由

使用方括号表示动态参数：

src/pages/api/users/[id].ts → /api/users/:id
src/pages/api/posts/[slug].ts → /api/posts/:slug
src/pages/api/users/[userId]/posts/[postId].ts → /api/users/:userId/posts/:postId

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

FlyClaw：零登录航班聚合查询工具，Python实现多源航班信息与价格搜索

4,000,000 周安装

飞书视频会议CLI工具：lark-vc技能详解，高效搜索与管理会议记录与纪要

29,600 周安装

Lark CLI妙记查询工具：快速获取飞书妙记元信息（标题、封面、时长）

28,100 周安装

Lark CLI Wiki API 使用指南：获取知识空间节点信息与权限管理

28,000 周安装

为每个 HTTP 方法导出命名函数。使用来自 astro 的 APIRoute 进行类型定义。每个处理程序接收一个 request 对象并返回一个 Response：

import type { APIRoute } from "astro";

export const GET: APIRoute = async ({ request }) => {
  console.log("Log from GET."); // 此消息会记录到你的 CLI。
  return new Response("Response from GET."); // 此响应在浏览器控制台中可见
};

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();
  console.log("Log POST with body: ", data); // 此消息会记录到你的 CLI。
  return new Response(JSON.stringify(data)); // 此响应在浏览器控制台中可见。
};

export const GET: APIRoute = async ({ params }) => {
  const { id } = params; // 来自 /api/users/[id]

  if (!id) {
    return new Response(JSON.stringify({ error: "ID required" }), {
      status: 400,
      statusText: "Bad Request",
      headers: { "Content-Type": "application/json" },
    });
  }

  // 使用 id 获取数据
};

使用 new URL(request.url).searchParams：

export const GET: APIRoute = async ({ request }) => {
  const url = new URL(request.url);
  const search = url.searchParams.get("search");
  const limit = parseInt(url.searchParams.get("limit") || "10", 10);
  const offset = parseInt(url.searchParams.get("offset") || "0", 10);

  // 使用查询参数
};

解析来自 POST/PUT/PATCH 请求的 JSON 请求体：

export const POST: APIRoute = async ({ request }) => {
  try {
    const body = await request.json();
    const { title, content } = body;

    if (!title || !content) {
      return new Response(
        JSON.stringify({ error: "Title and content required" }),
        {
          status: 400,
          statusText: "Bad Request",
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    // 处理数据
  } catch {
    return new Response(JSON.stringify({ error: "Invalid JSON" }), {
      status: 400,
      statusText: "Bad Request",
      headers: { "Content-Type": "application/json" },
    });
  }
};

const authHeader = request.headers.get("Authorization");
const contentType = request.headers.get("Content-Type");

始终返回一个带有适当状态码和响应头的 Response 对象：

// 200 OK
return new Response(JSON.stringify({ data: result }), {
  status: 200,
  headers: { "Content-Type": "application/json" },
});

// 201 Created
return new Response(JSON.stringify({ id: newId, ...data }), {
  status: 201,
  headers: { "Content-Type": "application/json" },
});

// 204 No Content (用于 DELETE)
return new Response(null, { status: 204 });

// 400 Bad Request
return new Response(JSON.stringify({ error: "Invalid input" }), {
  status: 400,
  statusText: "Bad Request",
  headers: { "Content-Type": "application/json" },
});

// 404 Not Found
return new Response(JSON.stringify({ error: "Not found" }), {
  status: 404,
  statusText: "Not Found",
  headers: { "Content-Type": "application/json" },
});

// 500 Internal Server Error
return new Response(JSON.stringify({ error: "Internal server error" }), {
  status: 500,
  statusText: "Internal Server Error",
  headers: { "Content-Type": "application/json" },
});

使用 Wix 内置的 HTTP 客户端 (httpClient.fetchWithAuth()) 从前端组件调用 HTTP 端点：

import { httpClient } from "@wix/essentials";

// GET 请求
const baseApiUrl = new URL(import.meta.url).origin;
const res = await httpClient.fetchWithAuth(
  `${baseApiUrl}/api/<your-endpoint-name>`,
);
const data = await res.text();

// POST 请求
const res = await httpClient.fetchWithAuth(
  `${baseApiUrl}/api/<your-endpoint-name>`,
  {
    method: "POST",
    body: JSON.stringify({ message: "Hello from frontend" }),
  },
);
const data = await res.json();

构建、部署与删除

要将 HTTP 端点投入生产环境，请构建并发布你的项目：

使用 build 命令构建项目资源。
（可选）使用 preview 命令创建预览 URL，以便与团队成员共享进行测试。
使用 release 命令发布你的项目。

发布后，端点即可通过生产环境 URL 访问并处理实时流量。

要删除 HTTP 端点，请删除 src/pages/api/ 下的文件并重新发布。

src/pages/api/
├── users.ts              # /api/users 端点
├── users/
│   └── [id].ts           # /api/users/:id 端点
└── posts.ts              # /api/posts 端点

严格的 TypeScript（不使用 any，显式返回类型）
使用来自 astro 的 APIRoute 对所有处理程序进行类型定义
对于 JSON，始终使用 JSON.stringify() 返回 Response 对象
正确的 HTTP 状态码（200、201、204、400、404、500）
在 JSON 响应中包含 Content-Type: application/json 响应头
在错误响应中包含 statusText
使用 try/catch 块处理错误
验证输入参数和请求体
对异步操作使用 async/await
不使用 @ts-ignore 注释

🇺🇸English

Wix Backend API Builder

Creates HTTP endpoints for Wix CLI applications — server-side routes that handle HTTP requests, process data, and return responses. HTTP endpoints are powered by Astro endpoints and are automatically discovered from the file system.

Key facts:

Files live in src/pages/api/ with .ts extension
Cannot be added via npm run generate — create files directly
Don't appear on the Extensions page in the app dashboard
No extension registration needed (auto-discovered)
Replace the legacy "HTTP functions" from the previous Wix CLI for Apps

Use Cases

Use HTTP endpoints when you need to:

Build REST APIs with multiple HTTP methods
Integrate with external APIs or services
Handle complex form submissions or file uploads
Serve dynamic content (images, RSS feeds, personalized data)
Access runtime data or server-side databases

File Structure and Naming

Basic Endpoint

File path determines the endpoint URL:

src/pages/api/<your-endpoint-name>.ts

Dynamic Routes

Use square brackets for dynamic parameters:

src/pages/api/users/[id].ts → /api/users/:id
src/pages/api/posts/[slug].ts → /api/posts/:slug
src/pages/api/users/[userId]/posts/[postId].ts → /api/users/:userId/posts/:postId

HTTP Methods

Export named functions for each HTTP method. Type with APIRoute from astro. Each handler receives a request object and returns a Response:

import type { APIRoute } from "astro";

export const GET: APIRoute = async ({ request }) => {
  console.log("Log from GET."); // This message logs to your CLI.
  return new Response("Response from GET."); // This response is visible in the browser console
};

export const POST: APIRoute = async ({ request }) => {
  const data = await request.json();
  console.log("Log POST with body: ", data); // This message logs to your CLI.
  return new Response(JSON.stringify(data)); // This response is visible in the browser console.
};

Request Handling

Path Parameters

export const GET: APIRoute = async ({ params }) => {
  const { id } = params; // From /api/users/[id]

  if (!id) {
    return new Response(JSON.stringify({ error: "ID required" }), {
      status: 400,
      statusText: "Bad Request",
      headers: { "Content-Type": "application/json" },
    });
  }

  // Use id to fetch data
};

Query Parameters

Use new URL(request.url).searchParams:

export const GET: APIRoute = async ({ request }) => {
  const url = new URL(request.url);
  const search = url.searchParams.get("search");
  const limit = parseInt(url.searchParams.get("limit") || "10", 10);
  const offset = parseInt(url.searchParams.get("offset") || "0", 10);

  // Use query parameters
};

Request Body

Parse JSON body from POST/PUT/PATCH requests:

export const POST: APIRoute = async ({ request }) => {
  try {
    const body = await request.json();
    const { title, content } = body;

    if (!title || !content) {
      return new Response(
        JSON.stringify({ error: "Title and content required" }),
        {
          status: 400,
          statusText: "Bad Request",
          headers: { "Content-Type": "application/json" },
        }
      );
    }

    // Process data
  } catch {
    return new Response(JSON.stringify({ error: "Invalid JSON" }), {
      status: 400,
      statusText: "Bad Request",
      headers: { "Content-Type": "application/json" },
    });
  }
};

Headers

const authHeader = request.headers.get("Authorization");
const contentType = request.headers.get("Content-Type");

Response Patterns

Always return a Response object with proper status codes and headers:

// 200 OK
return new Response(JSON.stringify({ data: result }), {
  status: 200,
  headers: { "Content-Type": "application/json" },
});

// 201 Created
return new Response(JSON.stringify({ id: newId, ...data }), {
  status: 201,
  headers: { "Content-Type": "application/json" },
});

// 204 No Content (for DELETE)
return new Response(null, { status: 204 });

// 400 Bad Request
return new Response(JSON.stringify({ error: "Invalid input" }), {
  status: 400,
  statusText: "Bad Request",
  headers: { "Content-Type": "application/json" },
});

// 404 Not Found
return new Response(JSON.stringify({ error: "Not found" }), {
  status: 404,
  statusText: "Not Found",
  headers: { "Content-Type": "application/json" },
});

// 500 Internal Server Error
return new Response(JSON.stringify({ error: "Internal server error" }), {
  status: 500,
  statusText: "Internal Server Error",
  headers: { "Content-Type": "application/json" },
});

Frontend Integration

Call HTTP endpoints from frontend components using Wix's built-in HTTP client (httpClient.fetchWithAuth()):

import { httpClient } from "@wix/essentials";

// GET request
const baseApiUrl = new URL(import.meta.url).origin;
const res = await httpClient.fetchWithAuth(
  `${baseApiUrl}/api/<your-endpoint-name>`,
);
const data = await res.text();

// POST request
const res = await httpClient.fetchWithAuth(
  `${baseApiUrl}/api/<your-endpoint-name>`,
  {
    method: "POST",
    body: JSON.stringify({ message: "Hello from frontend" }),
  },
);
const data = await res.json();

Build, Deploy, and Delete

To take HTTP endpoints to production, build and release your project:

Build the project assets using the build command.
Optionally create preview URLs using the preview command to share with team members for testing.
Release your project using the release command.

Once released, endpoints are accessible at production URLs and handle live traffic.

To delete an HTTP endpoint, remove the file under src/pages/api/ and release again.

Output Structure

src/pages/api/
├── users.ts              # /api/users endpoint
├── users/
│   └── [id].ts           # /api/users/:id endpoint
└── posts.ts              # /api/posts endpoint

Code Quality Requirements

Strict TypeScript (no any, explicit return types)
Type all handlers with APIRoute from astro
Always return Response objects with JSON.stringify() for JSON
Proper HTTP status codes (200, 201, 204, 400, 404, 500)
Include Content-Type: application/json header on JSON responses
Include statusText in error responses
Handle errors with try/catch blocks
Validate input parameters and request bodies
Use async/await for asynchronous operations
No @ts-ignore comments

Weekly Installs

196

Repository

wix/skills

GitHub Stars

First Seen

Jan 26, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode174

cursor95

codex90

gemini-cli88

github-copilot84

kimi-cli80

Lark Skill Maker 教程：基于飞书CLI创建AI技能，自动化工作流与API调用指南

27,800 周安装