企业官网建设流程全解析

本文基于 autoskills 仓库中收录的 deno-typescript 技能文档，系统讲解在 Deno 运行时下使用 TypeScript 的完整开发规范：涵盖编码风格、项目结构、模块系统、安全权限模型、HTTP 服务、数据库集成、测试与内置工具链等核心主题。读完本文，你将掌握一套可直接落地的 Deno + TypeScript 工程实践，并能理解 autoskills 如何在检测到 Deno 项目时自动为你安装这套技能。

一、技能背景：deno-typescript 在 autoskills 中的定位

autoskills 是一个"一条命令安装整套 AI 技能栈"的工具：它会扫描项目中的package.json、锁文件与各类配置文件，自动检测技术栈并为 Cursor、Claude Code 等 AI 编码助手安装对应的技能（SKILL），使其真正理解你的项目。deno-typescript正是其中面向 Deno 开发者的核心技能之一。

从仓库源码可以确认该技能的收录与分发链路：

• 检测规则定义在 skills-map.ts：当项目存在deno.json、deno.jsonc或deno.lock时，autoskills 判定为 Deno 项目，并推荐 6 个技能，其中包含mindrally/skills/deno-typescript；
• 技能清单与来源记录在 skills-registry/index.json：来源为mindrally/skills，收录了单个SKILL.md文件并附有 SHA-256 校验与审核记录；
• 安装行为由 installer.ts 实现：技能最终被安装到项目根目录的.agents/skills/<skill-name>/SKILL.md，安装前会先校验本地副本完整性，失败再走缓存或下载；
• 检测逻辑有测试兜底：在 tests/cli.test.ts 中，写入deno.json后执行--dry-run，断言输出包含Deno、deno-expert与deno-typescript。

此外，仓库还为 Deno 准备了完整的技能矩阵：deno-expert（专家级代码评审与调试）、deno-guidance（项目初始化与 CLI 基础）、deno-frontend、deno-deploy（边缘部署）与deno-sandbox（安全沙箱执行）。deno-typescript侧重"用 TypeScript 写 Deno 应用"的编码层规范，与它们互为补充。

二、TypeScript 通用编码规范

deno-typescript首先给出了一套与运行时无关的 TypeScript 编码纪律，这是所有 Deno 代码的基础。

2.1 基本原则

• 所有代码与文档使用英文；
• 变量与函数必须显式声明类型（含参数与返回值）；
• 避免使用any类型，需要时创建必要的具体类型；
• 使用 JSDoc 为公共类与方法撰写文档注释；
• 编写简洁、可维护、技术准确的代码；
• 优先使用函数式与声明式编程模式；
• 无需任何构建配置——Deno 原生直接运行 TypeScript。

最后一点是 Deno 与 Node.js 工作流最本质的差异：没有tsconfig编译前置、没有打包器介入，.ts文件即写即跑。

2.2 命名规范

2.3 函数设计

• 函数保持短小、单一职责；
• 简单操作优先使用箭头函数；
• 异步操作统一使用async/await；
• 多参数场景优先采用 RO-RO（Receive an Object, Return an Object）模式，即"收一个对象、返一个对象"，避免过长参数列表。

2.4 类型与接口

• 描述对象形状时优先使用interface而非type；
• 避免使用enum，改用const对象配合as const声明；
• 运行时校验使用 Zod，并通过z.infer推导静态类型；
• 不可变属性使用readonly修饰。

三、Deno 项目结构规范

技能文档给出了一套推荐目录结构，将"路由、中间件、服务、类型、工具"分层隔离：

src/ routes/ {resource}/ mod.ts handlers.ts validators.ts middleware/ auth.ts logger.ts services/ {domain}_service.ts types/ mod.ts utils/ mod.ts deps.ts main.ts deno.json

这套结构的关键设计意图：每个资源路由自成目录，handlers.ts只做请求分发，validators.ts承载 Zod 校验逻辑；deps.ts作为全项目唯一的依赖出口集中管理第三方导入；main.ts作为程序入口只做装配。配合根目录deno.json，一个 Deno 项目的边界就非常清晰。

四、模块系统：deps.ts 与 import map

Deno 使用原生 ES Modules，且必须带显式文件扩展名（如./user_service.ts，不可省略.ts）。技能文档强调两种集中管理依赖的方式：

4.1 deps.ts 集中导出模式

// deps.ts - centralized dependencies export { serve } from "https://deno.land/std@0.208.0/http/server.ts"; export { z } from "https://deno.land/x/zod@v3.22.4/mod.ts";

所有业务模块只从deps.ts导入，杜绝散落在各文件的裸 URL 依赖，升级依赖时只需改动一个文件。

4.2 deno.json 中的 import map

{ "imports": { "std/": "https://deno.land/std@0.208.0/", "hono": "https://deno.land/x/hono@v3.11.7/mod.ts" } }

在deno.json的imports字段中为常用依赖定义别名后，业务代码即可使用裸标识符：import { serve } from "std/http/server.ts"。

需要注意的版本语境：deno-typescript技能文档中的示例使用了基于 URL 的导入写法；而本仓库配套的 deno-guidance 与 deno-expert 两份技能则明确强调：当前官方推荐优先级为JSR 包（jsr:）优先 → npm 包（npm:）其次 → 旧的 URL 式注册表已废弃。标准库统一位于 JSR 的@std/命名空间下，例如import { serve } from "@std/http"。实际新建项目时，建议采用 JSR 裸标识符配合deno add jsr:@std/http管理依赖，与最新生态保持一致。

五、安全模型：默认安全的权限系统

Deno 默认拒绝一切权限，这是其安全模型的核心。运行程序时必须以命令行参数显式授权，技能文档给出了权限 flag 的完整清单：

# Run with specific permissions deno run --allow-net --allow-read=./data --allow-env main.ts # Permission flags --allow-net=example.com # Network access to specific domains --allow-read=./path # File read access --allow-write=./path # File write access --allow-env=API_KEY # Environment variable access --allow-run=cmd # Subprocess execution

注意每个 flag 都支持最小化授权：--allow-net=example.com只放行指定域名，--allow-read=./path只开放指定目录，--allow-env=API_KEY只暴露指定变量。原则是"按需申请，最小授权"。

除命令行参数外，还可以在运行时通过 API 动态请求权限：

// Programmatic permission requests const status = await Deno.permissions.request({ name: "net", host: "api.example.com" }); if (status.state === "granted") { // Network access granted }

返回的status.state取值可为"granted"、"denied"或"prompt"，程序可据此决定后续分支。配套的 deno-guidance 还提醒：忘记加权限 flag 时 Deno 会提示 "Requires net access" 之类的错误，此时应显式授予代码所需的精确权限，而不是用--allow-all一刀切。

六、HTTP 服务：用 Deno.serve 快速起服务

技能文档推荐使用运行时内置的Deno.serve编写 HTTP 服务，无需任何框架依赖：

// Simple HTTP server Deno.serve({ port: 8000 }, (req) => { const url = new URL(req.url); if (url.pathname === "/api/users" && req.method === "GET") { return Response.json({ users: [] }); } return new Response("Not Found", { status: 404 }); });

要点解析：

• 处理函数接收标准Request对象，返回标准Response对象，完全基于 Web 标准；
• 使用new URL(req.url)解析路径与查询参数，实现简单的路由分发；
• 直接返回Response.json(...)即可输出 JSON，省去手动设置Content-Type的样板代码；
• { port: 8000 }为选项对象，还可配置hostname、onListen等。

七、使用 Hono 框架构建路由

当路由规模增长，可引入 Hono 获得更完善的中间件与路由体验。技能文档展示了最简集成方式：

import { Hono } from "https://deno.land/x/hono/mod.ts"; const app = new Hono(); app.get("/", (c) => c.text("Hello Deno!")); app.get("/api/users", (c) => c.json({ users: [] })); Deno.serve(app.fetch);

Hono 的路由处理器返回响应对象（c.text、c.json），应用本身暴露app.fetch方法，可以直接交给Deno.serve托管，两者无缝衔接。从源码结构看，这一模式把框架路由与运行时 HTTP 服务的职责彻底解耦，后续若需要迁移到其他运行时，app.fetch依然可复用。

八、使用 Fresh 全栈框架

对于需要服务端渲染（SSR）的完整应用，技能文档推荐 Fresh——一个基于岛屿架构（Islands Architecture）的 Deno 原生全栈框架：

// routes/index.tsx import { PageProps } from "$fresh/server.ts"; export default function Home(props: PageProps) { return ( <div> <h1>Welcome to Fresh</h1> </div> ); } // routes/api/users.ts import { Handlers } from "$fresh/server.ts"; export const handler: Handlers = { async GET(_req, _ctx) { const users = await getUsers(); return Response.json(users); }, };

Fresh 采用文件路由约定：routes/index.tsx对应首页组件，routes/api/users.ts通过导出的handler对象声明式定义 API 端点（GET、POST等方法各一个属性）。这种"路由文件即页面、API 与 UI 同目录"的组织方式，与技能文档第三节的项目结构规范一脉相承。

九、数据库集成：内置的 Deno KV

技能文档推荐使用 Deno 内置的键值存储 Deno KV 处理轻量数据持久化，无需单独部署数据库：

// Using Deno KV (built-in key-value store) const kv = await Deno.openKv(); // Set a value await kv.set(["users", "1"], { name: "John", email: "john@example.com" }); // Get a value const result = await kv.get(["users", "1"]); console.log(result.value); // List values const entries = kv.list({ prefix: ["users"] }); for await (const entry of entries) { console.log(entry.key, entry.value); }

关键 API 语义：

• 键是数组形式的层级路径（如["users", "1"]），天然支持按前缀组织数据；
• kv.set可存入任意可序列化对象，kv.get返回带value的KvEntry；
• kv.list({ prefix: [...] })返回异步迭代器，配合for await可流式遍历某一前缀下的全部记录；
• 数据一致性由 Deno 运行时保证，kv.set在并发冲突时返回versionstamp可做乐观锁。

十、环境变量读取

访问环境变量必须配合--allow-env权限：

// Access environment variables (requires --allow-env) const apiKey = Deno.env.get("API_KEY");

需要读取本地.env文件时，可结合标准库的 dotenv 模块：

import { load } from "https://deno.land/std/dotenv/mod.ts"; const env = await load();

Deno.env.get()是运行时内置 API；load()则负责解析.env文件内容并合并进当前环境。生产环境建议直接将API_KEY这类敏感值注入进程环境，避免把密钥写入仓库。

十一、使用内置测试运行器

Deno 自带测试运行器，支持 BDD 风格（describe/it）与断言库，技能文档给出了完整的服务测试示例：

// user_test.ts import { assertEquals, assertRejects } from "https://deno.land/std/assert/mod.ts"; import { describe, it, beforeEach } from "https://deno.land/std/testing/bdd.ts"; import { getUser, createUser } from "./user_service.ts"; describe("User Service", () => { beforeEach(() => { // Setup }); it("should create a user", async () => { const user = await createUser({ name: "John", email: "john@example.com" }); assertEquals(user.name, "John"); }); it("should throw for invalid email", async () => { await assertRejects( () => createUser({ name: "John", email: "invalid" }), Error, "Invalid email" ); }); }); // Run tests // deno test --allow-net --allow-read

要点：

• assertEquals用于值断言，assertRejects用于断言异步操作抛出指定错误（可附带错误类型与消息）；
• describe/it/beforeEach提供 BDD 组织能力，beforeEach中做测试前置准备；
• 测试文件按*_test.ts约定命名，deno test自动发现；
• 若被测代码需要网络或文件访问，运行测试时必须带对应权限 flag：deno test --allow-net --allow-read。

十二、内置工具链：fmt / lint / check / bundle / compile / doc / info

Deno 将现代工程工具全部内置，无需安装任何第三方工具链：

# Formatting deno fmt # Linting deno lint # Type checking deno check main.ts # Bundle deno bundle main.ts bundle.js # Compile to executable deno compile --allow-net main.ts # Documentation generation deno doc main.ts # Dependency inspection deno info main.ts

各命令用途：

• deno fmt：格式化全部源码，配套 deno-guidance 建议在 CI 中使用deno fmt --check只校验不修改，避免 CI 悄悄改文件；
• deno lint：静态检查，默认启用recommended规则集；
• deno check main.ts：全量类型检查（运行时本身会做增量类型检查，check用于显式全量校验）；
• deno bundle：将入口及其依赖打包为单一 JS 文件；
• deno compile：编译为独立可执行二进制（含运行时），携带所需权限 flag 即可分发部署；
• deno doc：从 JSDoc 注释生成文档，也可deno doc <package>查看任意 JSR/npm 包的本地文档；
• deno info：分析入口的依赖图与模块缓存位置。

十三、deno.json 配置详解

deno.json是 Deno 的配置文件（功能类似package.json但更精简），技能文档给出了一个完整的配置示例：

{ "tasks": { "dev": "deno run --watch --allow-net --allow-env main.ts", "start": "deno run --allow-net --allow-env main.ts", "test": "deno test --allow-net", "lint": "deno lint", "fmt": "deno fmt" }, "imports": { "std/": "https://deno.land/std@0.208.0/", "@/": "./src/" }, "compilerOptions": { "strict": true, "lib": ["deno.window"] }, "lint": { "rules": { "tags": ["recommended"] } }, "fmt": { "indentWidth": 2, "singleQuote": true } }

逐项说明：

配套的 deno-guidance 还补充了两个实用配置：用"exclude"在顶层排除目录（如["build/"]），或分别在fmt/lint下排除特定目录，避免构建产物被格式化或检查。

十四、错误处理模式

技能文档给出了一套面向 HTTP 服务的统一错误处理范式：自定义错误类 + 顶层 try/catch + 结构化 JSON 响应。

class AppError extends Error { constructor( message: string, public statusCode: number = 500, public code: string = "INTERNAL_ERROR" ) { super(message); this.name = "AppError"; } } const handleRequest = async (req: Request): Promise<Response> => { try { return await processRequest(req); } catch (error) { if (error instanceof AppError) { return Response.json( { error: error.message, code: error.code }, { status: error.statusCode } ); } console.error(error); return Response.json( { error: "Internal Server Error" }, { status: 500 } ); } };

设计要点：

• AppError通过构造函数参数同时携带业务错误消息、HTTP 状态码与机器可读的错误码，默认值分别兜底为500与"INTERNAL_ERROR"；
• 业务层抛出AppError时，统一转换为{ error, code }的 JSON 响应并映射对应状态码；
• 未知异常记录console.error后返回通用500响应，避免向客户端泄露内部细节。

十五、拥抱 Web 标准与性能实践

15.1 Web 标准 API

Deno 全面拥抱 Web 标准，技能文档明确建议优先使用以下内置 API 而非第三方库：

• fetch()发起 HTTP 请求；
• Request与Response对象承载请求与响应；
• URL与URLSearchParams解析地址与查询参数；
• Web Crypto API处理加密；
• Streams API处理数据流；
• FormData处理 multipart 表单数据。

这套 API 与浏览器环境完全一致，意味着写一次代码即可在浏览器与 Deno 之间复用认知。

15.2 性能实践清单

• 大数据处理使用 Web Streams，边读边处理、降低内存峰值；
• 高频键值读写利用 Deno KV 的内置存储；
• 高并发 HTTP 场景直接使用Deno.serve（基于现代异步 I/O 实现）；
• 生产部署前用deno compile编译为独立可执行文件，减少启动开销并简化分发。

十六、在 autoskills 中启用并查看该技能

deno-typescript技能会随 autoskills 的检测流程自动进入你的项目。实操路径如下：

1. 触发检测：在项目根目录运行npx autoskills（要求 Node.js >= 22），autoskills 扫描到deno.json/deno.jsonc/deno.lock即识别为 Deno 项目；
2. 预览确认：可先运行npx autoskills --dry-run，输出中应包含Deno及deno-expert、deno-typescript等技能名（对应仓库测试 tests/cli.test.ts 的断言行为）；
3. 一键安装：确认后技能被安装到项目.agents/skills/deno-typescript/SKILL.md（安装逻辑见 installer.ts），若目标是 Claude Code 还会自动生成CLAUDE.md汇总说明；
4. 查阅原文：本文所有规范均可在仓库原文 packages/autoskills/skills-registry/deno-typescript/SKILL.md 中直接查阅，其收录来源与校验信息见 skills-registry/index.json。

此后，你的 AI 编码助手在 Deno 项目中编写、评审代码时，就会自动遵循本文所述的命名规范、权限最小化、内置工具链与错误处理模式，让生成的代码更贴合 Deno 生态的最佳实践。