sanbuphy
f35cddeb8b
## 新增组件 (14个) - CodeSmellDemo.vue: 代码异味识别演示 - DecisionMatrixDemo.vue: 决策矩阵工具 - DesignPatternCatalogDemo.vue: 设计模式目录 - DocStructureDemo.vue: 文档结构示例 - LicenseComparisonDemo.vue: 开源许可证对比 - OpenSourceWorkflowDemo.vue: 开源协作流程 - PatternPlaygroundDemo.vue: 设计模式演练场 - RefactoringDemo.vue: 重构实战演示 - SecurityChecklistDemo.vue: 安全检查清单 - TDDCycleDemo.vue: TDD 循环演示 - TechRadarDemo.vue: 技术雷达图 - TechWritingPracticeDemo.vue: 技术写作实践 - TestPyramidDemo.vue: 测试金字塔 - WebSecurityDemo.vue: Web 安全演示 ## 文档更新 (7篇) - code-quality-refactoring.md: 代码质量与重构 - design-patterns.md: 设计模式 - open-source-collaboration.md: 开源协作 - security-thinking.md: 安全思维 - technical-writing.md: 技术写作 - technology-selection.md: 技术选型 - testing-strategies.md: 测试策略 ## 其他变更 - 将 browser-as-os.md 内容合并到 computer-networks.md - 更新 .gitignore 和 theme/index.js
122 lines
3.8 KiB
Vue
122 lines
3.8 KiB
Vue
<template>
|
||
<div class="tech-writing-demo">
|
||
<div class="demo-label">技术写作对比 ── 点击切换案例</div>
|
||
|
||
<div class="tabs">
|
||
<button
|
||
v-for="(c, i) in cases"
|
||
:key="i"
|
||
class="tab"
|
||
:class="{ active: current === i }"
|
||
@click="current = i"
|
||
>{{ c.icon }} {{ c.name }}</button>
|
||
</div>
|
||
|
||
<div class="compare">
|
||
<div class="col bad">
|
||
<div class="col-title">❌ 差的写法</div>
|
||
<pre><code>{{ cases[current].bad }}</code></pre>
|
||
</div>
|
||
<div class="col good">
|
||
<div class="col-title">✅ 好的写法</div>
|
||
<pre><code>{{ cases[current].good }}</code></pre>
|
||
</div>
|
||
</div>
|
||
|
||
<div class="tips">
|
||
<strong>改进要点：</strong>
|
||
<span v-for="(t, i) in cases[current].tips" :key="i" class="tip-tag">{{ t }}</span>
|
||
</div>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
const current = ref(0)
|
||
|
||
const cases = [
|
||
{
|
||
name: '函数注释',
|
||
icon: '💬',
|
||
bad: `// 处理数据
|
||
function process(d) {
|
||
// ...
|
||
}`,
|
||
good: `/**
|
||
* 将原始订单数据转换为发票格式
|
||
* @param {Order} order - 原始订单对象
|
||
* @returns {Invoice} 格式化后的发票
|
||
* @throws {ValidationError} 订单数据不完整时
|
||
*/
|
||
function toInvoice(order) {
|
||
// ...
|
||
}`,
|
||
tips: ['说明"为什么"而非"是什么"', '标注参数类型和返回值', '说明异常情况']
|
||
},
|
||
{
|
||
name: 'API 说明',
|
||
icon: '🔌',
|
||
bad: `POST /api/users
|
||
发送用户数据创建用户。`,
|
||
good: `POST /api/users
|
||
创建新用户账号。
|
||
|
||
请求体：
|
||
{
|
||
"name": "张三", // 必填，2-50字符
|
||
"email": "a@b.com" // 必填，有效邮箱
|
||
}
|
||
|
||
成功响应 201：
|
||
{ "id": "u_123", "name": "张三" }
|
||
|
||
错误响应 400：
|
||
{ "error": "邮箱格式无效" }`,
|
||
tips: ['提供完整的请求/响应示例', '标注必填/选填', '列出错误场景']
|
||
},
|
||
{
|
||
name: '变更日志',
|
||
icon: '📝',
|
||
bad: `v2.1 - 修了一些bug，加了新功能`,
|
||
good: `## v2.1.0 (2025-01-15)
|
||
|
||
### 新增
|
||
- 支持批量导出 PDF 格式报表
|
||
|
||
### 修复
|
||
- 修复登录页在 Safari 下白屏的问题 (#234)
|
||
|
||
### 变更
|
||
- 最低 Node.js 版本要求从 16 升至 18`,
|
||
tips: ['按类型分类（新增/修复/变更）', '关联 Issue 编号', '标注版本号和日期']
|
||
}
|
||
]
|
||
</script>
|
||
|
||
<style scoped>
|
||
.tech-writing-demo {
|
||
border: 1px solid var(--vp-c-divider);
|
||
border-radius: 8px;
|
||
background: var(--vp-c-bg-soft);
|
||
padding: 1rem 1.2rem;
|
||
margin: 1rem 0;
|
||
}
|
||
.demo-label { font-size: 0.78rem; font-weight: bold; color: var(--vp-c-text-2); margin-bottom: 1rem; text-align: center; }
|
||
.tabs { display: flex; gap: 6px; margin-bottom: 1rem; flex-wrap: wrap; }
|
||
.tab { padding: 6px 14px; border-radius: 6px; border: 1px solid var(--vp-c-divider); background: var(--vp-c-bg); cursor: pointer; font-size: 0.85rem; transition: all 0.2s; }
|
||
.tab.active { background: var(--vp-c-brand); color: #fff; border-color: var(--vp-c-brand); }
|
||
|
||
.compare { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-bottom: 10px; }
|
||
@media (max-width: 640px) { .compare { grid-template-columns: 1fr; } }
|
||
.col { border-radius: 6px; overflow: hidden; }
|
||
.col-title { font-size: 0.72rem; padding: 4px 10px; border-bottom: 1px solid var(--vp-c-divider); }
|
||
.col.bad .col-title { background: #fef2f2; color: #991b1b; }
|
||
.col.good .col-title { background: #ecfdf5; color: #065f46; }
|
||
:root.dark .col.bad .col-title { background: #1c0606; color: #fca5a5; }
|
||
:root.dark .col.good .col-title { background: #031c14; color: #6ee7b7; }
|
||
.col pre { margin: 0; padding: 8px; font-size: 0.78rem; line-height: 1.5; overflow-x: auto; background: var(--vp-c-bg); }
|
||
|
||
.tips { font-size: 0.83rem; display: flex; align-items: center; gap: 6px; flex-wrap: wrap; }
|
||
.tip-tag { padding: 2px 8px; border-radius: 10px; background: var(--vp-c-brand-soft); font-size: 0.75rem; }
|
||
</style>
|