fix(attribution): Skill 文档未清晰说明 HTTP 云函数的代码编写规范 (issue_mns1xuxr_arrdn2)

Author: CodeBuddy Attribution Bot

config/source/skills/cloud-functions/references/http-functions.md

@@ -10,6 +10,7 @@ HTTP Functions are standard web services, not `exports.main(event, context)` han
 - Listen on port `9000`.
 - Ship an executable `scf_bootstrap` file.
 - Include runtime dependencies in the package; HTTP Functions do not auto-install `node_modules` for you.
+- For simple HTTP APIs, prefer the Node.js native `http` module so the function shape stays explicit and dependency-light. Only introduce Express, Koa, NestJS, or similar frameworks when the user explicitly asks for one or the service complexity justifies it.
 
 ## Minimal structure
 
@@ -25,7 +26,7 @@ my-http-function/
 
 ```bash
 #!/bin/bash
-node index.js
+/var/lang/node18/bin/node index.js
 ```
 
 Requirements:
@@ -37,54 +38,148 @@ Requirements:
 ## Minimal Node.js example
 
 ```javascript
-const express = require("express");
-const app = express();
+const http = require("http");
+const { URL } = require("url");
+
+function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(data));
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+
+    req.on("data", (chunk) => {
+      raw += chunk;
+    });
+
+    req.on("end", () => {
+      if (!raw) {
+        resolve({});
+        return;
+      }
+
+      try {
+        resolve(JSON.parse(raw));
+      } catch (error) {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+
+    req.on("error", reject);
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url || "/", "http://127.0.0.1");
+
+  if (req.method === "GET" && url.pathname === "/health") {
+    sendJson(res, 200, { ok: true });
+    return;
+  }
 
-app.use(express.json());
+  if (req.method === "POST" && url.pathname === "/echo") {
+    try {
+      const body = await readJsonBody(req);
+      sendJson(res, 200, { received: body });
+    } catch (error) {
+      sendJson(res, 400, { error: error.message });
+    }
+    return;
+  }
 
-app.get("/health", (req, res) => {
-  res.json({ ok: true });
+  sendJson(res, 404, { error: "Not Found" });
 });
 
-app.listen(9000);
+server.listen(9000);
 ```
 
+## Code-writing rules
+
+- Do not write HTTP Functions as `exports.main = async (event, context) => {}`. That is the Event Function contract.
+- Start an HTTP server explicitly with `http.createServer(...)` or a framework app, and always bind to port `9000`.
+- Treat routing, method checks, and body parsing as part of the function code. With the native `http` module, parse `req.url` yourself and read the request body from the stream before calling `JSON.parse`.
+- Return JSON responses explicitly and set `Content-Type` yourself, for example `application/json; charset=utf-8`.
+- Keep unsupported routes and methods explicit. Return `404` for unknown paths, and return `405` when the path exists but the HTTP method is not allowed.
+- Keep `scf_bootstrap`, `index.js`, `package.json`, and any bundled dependencies in the function directory that will be uploaded.
+
 ## Request handling rules
 
-- `req.query` -> query string values.
-- `req.body` -> parsed request body, but only after body-parsing middleware is configured.
+- With Node native `http`, use `new URL(req.url, "http://127.0.0.1")` and read `url.searchParams` for query values.
+- With Node native `http`, `req.body` does not exist. Read the body stream manually, then parse JSON yourself.
 - `req.headers` -> incoming HTTP headers.
-- `req.params` -> path parameters.
-- Always send a response with `res.json()`, `res.send()`, or `res.status(...).json()`.
+- Path parameters are framework-level conveniences. With the native `http` module, match `url.pathname` yourself.
+- Always send a response explicitly. With Node native `http`, use `res.writeHead(...)` and `res.end(...)`.
 - Return meaningful status codes such as `400`, `401`, `404`, `405`, `500`.
 
 ### Example with method checks
 
 ```javascript
-const express = require("express");
-const app = express();
-
-app.use(express.json());
-
-app.post("/users", (req, res) => {
-  const { name, email } = req.body;
-
-  if (!name || !email) {
-    return res.status(400).json({ error: "name and email are required" });
+const http = require("http");
+const { URL } = require("url");
+
+function sendJson(res, statusCode, data) {
+  res.writeHead(statusCode, { "Content-Type": "application/json; charset=utf-8" });
+  res.end(JSON.stringify(data));
+}
+
+function readJsonBody(req) {
+  return new Promise((resolve, reject) => {
+    let raw = "";
+
+    req.on("data", (chunk) => {
+      raw += chunk;
+    });
+
+    req.on("end", () => {
+      if (!raw) {
+        resolve({});
+        return;
+      }
+
+      try {
+        resolve(JSON.parse(raw));
+      } catch (error) {
+        reject(new Error("Invalid JSON body"));
+      }
+    });
+
+    req.on("error", reject);
+  });
+}
+
+const server = http.createServer(async (req, res) => {
+  const url = new URL(req.url || "/", "http://127.0.0.1");
+
+  if (url.pathname === "/users" && req.method === "POST") {
+    try {
+      const { name, email } = await readJsonBody(req);
+
+      if (!name || !email) {
+        sendJson(res, 400, { error: "name and email are required" });
+        return;
+      }
+
+      sendJson(res, 201, { name, email });
+    } catch (error) {
+      sendJson(res, 400, { error: error.message });
+    }
+
+    return;
   }
 
-  return res.status(201).json({ name, email });
-});
+  if (url.pathname === "/users") {
+    sendJson(res, 405, { error: "Method Not Allowed" });
+    return;
+  }
 
-app.all("/{*splat}", (req, res) => {
-  res.status(405).json({ error: "Method Not Allowed" });
+  sendJson(res, 404, { error: "Not Found" });
 });
 
-app.listen(9000);
+server.listen(9000);
 ```
 
-Express 5 note: do not use bare `*` or `/*` here. Express 5 uses `path-to-regexp` with named wildcards, so `app.all("/{*splat}", ...)` is the safe catch-all form when you also need to match the root path `/`.
-
 ## Deployment flow
 
 Prefer `manageFunctions` over CLI in agent flows.