API 文档作品集
Source: Dev.to
请提供您希望翻译的文本内容，我将为您翻译成简体中文。
概览
我的黑客马拉松目标是打造一个 脱颖而出 同时又 易于接近 的作品集。
我选择了 API 文档风格（类似 Swagger / Postman）来体现我的开发者身份，但仍保持对非技术访客的友好体验。
- 单一数据源： 所有个人信息都存放在一个
data.json文件中，更新轻松无痛。 - 技术栈： React + TypeScript，提供可扩展性和类型安全；Tailwind CSS，实现快速且一致的 UI 设计。
- 使用的工具：
- Gemini – 创意提示工程助理。
- Antigravity IDE (Gemini 3 Pro) – 高级前端审查、重构、错误修复、UI/UX 反馈。
- Google Cloud Run – 部署平台。
我遵循了 Google 科学家的提示工程指南，运用了一次性提示、回退思考和树状思考等技术。精选的提示示例见下文。
Prompt 1 – 重构简历页面以从 JSON 获取数据
上下文：
我们正在转向 数据驱动 架构。所有内容现在都存放在 data.json 中。
任务：
重构 “Resume/IDE Viewer” 页面（HTML/JS），使其动态加载 data.json 中的内容。
要求
-
JSON 结构（精确形状）
{ "resume": { "pdf_path": "/assets/cv.pdf", "filename": "cv_xxx_backend.pdf", "last_updated": "2026-01-12", "raw_data": { "name": "XXX", "role": "Junior Backend Developer", "stack": ["Python", "Django", "Docker"] } } } -
TypeScript 逻辑（获取 & DOM 操作）
- 页面加载时：
fetch('./data.json')。 - 更新 PDF： 找到
<iframe>（或类似元素），将其src设置为resume.pdf_path。 - 更新 “Raw” 视图： 将 “Raw (JSON)” 选项卡中的代码块填充为
resume.raw_data的美化后 JSON。 - 更新 UI 标签： 将面包屑/文件路径标签改为
resume.filename。
- 页面加载时：
-
HTML 更改
- 移除 PDF 容器中任何硬编码的
src（留空或显示加载中动画）。 - 为 JS 目标添加唯一 ID，例如：
id="pdf-viewer"id="json-code-block"id="file-name-label"
- 移除 PDF 容器中任何硬编码的
可交付成果
以下是满足上述要求的 最小 HTML 片段 与 更新后的 JavaScript（兼容 TypeScript）。
HTML（摘录）
<!-- PDF viewer -->
<iframe id="pdf-viewer" src=""></iframe>
<!-- Tabs -->
<button id="preview-tab">Preview</button>
<button id="raw-tab">Raw (JSON)</button>
<!-- JSON code block -->
<pre id="json-code-block"></pre>
<!-- Breadcrumb / filename label -->
<span id="file-name-label"></span>JavaScript / TypeScript（ES6）
// src/utils/loadResume.ts
interface ResumeRaw {
name: string;
role: string;
stack: string[];
}
interface ResumeData {
pdf_path: string;
filename: string;
last_updated: string;
raw_data: ResumeRaw;
}
interface PortfolioJSON {
resume: ResumeData;
}
/**
* Fetches `data.json`, updates the DOM, and handles errors.
*/
async function initResumeViewer(): Promise<void> {
try {
const response = await fetch('./data.json');
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const data: PortfolioJSON = await response.json();
const { pdf_path, filename, raw_data } = data.resume;
// ---- Update PDF viewer ----
const pdfViewer = document.getElementById('pdf-viewer') as HTMLIFrameElement;
if (pdfViewer) pdfViewer.src = pdf_path;
// ---- Update filename breadcrumb ----
const fileLabel = document.getElementById('file-name-label');
if (fileLabel) fileLabel.textContent = filename;
// ---- Populate Raw JSON view ----
const jsonBlock = document.getElementById('json-code-block');
if (jsonBlock) {
const pretty = JSON.stringify(raw_data, null, 2);
jsonBlock.textContent = pretty;
}
} catch (err) {
console.error('Failed to load resume data:', err);
// Optional: display a user‑friendly fallback UI
}
}
// Run on DOM ready
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', initResumeViewer);
} else {
initResumeViewer();
}Prompt 2 – UX Audit for Non‑Technical Users (Recruiter Persona)
Role: Senior UX Researcher paired with a Non‑Technical Tech Recruiter (HR Manager).
Context:
The portfolio uses a heavy API‑Documentation / CLI theme: dark mode, monospaced fonts, terminal‑style inputs, JSON code blocks, sidebar navigation (Stripe‑Docs style), and a command palette.
Problem:
The design may be over‑engineered, potentially confusing recruiters who lack coding experience, increasing cognitive load and navigation friction.
Heuristic Evaluation
| Friction Point | Why it fails HR | Thematic Solution |
|---|---|---|
| Bio text inside a JSON string | 难以快速阅读；括号/引号带来视觉噪音；招聘人员更倾向于直接扫描纯文本。 | 将简介渲染为普通段落文字，但在左侧保留细微的行号栏（类似 IDE），以保持“代码”感。 |
| Navigation via a terminal‑style command palette | 需要输入或记住指令；为一次简单查询增加了不必要的交互步骤。 | 将命令面板保留为可选快捷键，同时提供一个显眼的、传统的顶部导航栏，标注清晰的标签（About、Projects、Resume）。 |
| Work Experience displayed as raw JSON objects | 招聘人员期望使用项目符号或卡片形式；JSON 格式掩盖了时间顺序和成就。 | 使用卡片展示每个岗位，卡片外观模仿代码块（边框、等宽字体），内容采用自然语言呈现日期、职位和职责。 |
| Sidebar mimicking API docs with collapsible sections | 层级过多；招聘人员可能错过“Resume”链接。 | 将侧边栏折叠为最少的顶层项目，并在页眉添加固定的“Download Resume”按钮。 |
| Heavy use of dark background with low‑contrast text | 对不习惯暗色编码环境的用户可读性下降。 | 提高对比度（例如，深灰背景上的浅灰文字），并加入“light mode”切换以提升可访问性。 |
| “Raw JSON” view of the resume | 对招聘人员没有价值，显得技术化且令人望而却步。 | 将原始视图放在“Advanced”切换后面，主要提供干净的、可打印的 PDF 预览作为简历的默认访问方式。 |
| Terminal‑style input prompts for project demos | 需要输入指令才能查看演示；对一次点击即可的操作增加了摩擦。 | 替换为可点击的“Run Demo”按钮，保留终端风格的边框和光标动画，营造命令行的视觉感受而无需实际输入。 |
Breadcrumbs showing file paths (e.g., /cv_xxx_backend.pdf) | 可能让人困惑；招聘人员更期待看到“Resume”等明确标签。 | 同时显示：友好的标签（“Resume”）和技术路径面包屑，后者使用更小的次要字体。 |
Specific Questions Answered
| Question | Recommendation |
|---|---|
| Should I keep the “Terminal Input” as the primary navigation? | No. 将其作为可选快捷键保留给高级用户。为招聘人员提供传统、标签清晰的导航栏。 |
| How can I display “Work Experience” so it looks like code but reads like a story? | 使用卡片组件，外观带有代码块边框和等宽字体，但内容采用自然语言句子。左侧加入细微的行号，以保持开发者氛围。 |
| Is the “Raw JSON” view of my resume necessary? | Only as an advanced option. 将其放在“Advanced / Raw Data”切换后面。默认视图应为干净的、可打印的 PDF 预览，并配有显眼的“Download”按钮。 |
Summary
- Maintain the technical aesthetic (dark theme, code‑like borders, line numbers) while simplifying interactions for non‑technical users.
- Prioritize readability: plain text for bios, bullet points for experience, high‑contrast colors.
- Offer progressive disclosure: advanced JSON or terminal features hidden behind toggles, with a clean primary view for recruiters.
es 被隐藏在可选的切换按钮后面，使主要流程保持简洁。
实现这些桥接将让招聘人员在 6 秒扫描窗口 内找到关键信息（姓名、角色、技术栈、简历），同时保留作品集独特的 API 文档风格。
我为这个项目将作品集本身变成一次实验感到自豪。与其只关注视觉效果，我把它当作一个系统来对待：可维护、可扩展，并且以数据驱动。围绕单一 JSON 源设计整个站点，使我能够快速迭代，并在整个黑客马拉松期间保持结构的整洁。
我尤其为将 AI 视为协作者而非仅仅是代码生成器感到骄傲。通过优化提示并运用各种技巧，我能够使用 Gemini 和 Antigravity Agents 作为创意和技术审阅者，帮助我改进架构决策、UI/UX 以及整体清晰度。