CMS 前端内容渲染边界：Markdown、接口和页面如何配合

// ❌ 坏做法：分类合并逻辑散落在页面组件里
// app/[locale]/blog/_components/sidebar.tsx
 
interface SidebarProps {
  cmsCategories: Array<{ id: number; name: string; count: number }>
  localCategories: string[]
  articles: Article[]
}
 
export function Sidebar({ cmsCategories, localCategories, articles }: SidebarProps) {
  // 手动合并两个来源，逻辑和 UI 耦合
  const allCategories = [
    ...cmsCategories.map(c => ({
      label: c.name,
      count: c.count,
      // 这里没有处理同名分类的合并
    })),
    ...localCategories.map(name => ({
      label: name,
      count: articles.filter(a => a.categories?.includes(name)).length,
    })),
  ]
 
  return (
    <nav>
      {allCategories.map(cat => (
        <span key={cat.label}>
          {cat.label} ({cat.count})
        </span>
      ))}
    </nav>
  )
}

// ✅ 好做法：分类合并在数据层完成，页面组件只消费结果
// lib/content/category-merger.ts
 
interface UnifiedCategory {
  // 唯一标识：CMS 分类用原始 ID，本地分类用 slug 化的名称
  id: string
  name: string
  // 合并后的文章计数
  articleCount: number
  // 来源标记，方便调试
  sources: Array<'cms' | 'local'>
}
 
interface CmsCategory {
  id: number
  name: string
  count: number
}
 
export function mergeCategories(
  cmsCategories: CmsCategory[],
  localCategoryNames: string[],
): UnifiedCategory[] {
  const categoryMap = new Map<string, UnifiedCategory>()
 
  // 先写入 CMS 分类
  for (const cat of cmsCategories) {
    const id = `cms-${cat.id}`
    categoryMap.set(cat.name, {
      id,
      name: cat.name,
      articleCount: cat.count,
      sources: ['cms'],
    })
  }
 
  // 本地分类：如果同名已存在则合并计数，否则新增
  for (const name of localCategoryNames) {
    const existing = categoryMap.get(name)
    if (existing) {
      // 同名分类合并：计数相加，标记多来源
      existing.articleCount += 1
      if (!existing.sources.includes('local')) {
        existing.sources.push('local')
      }
    } else {
      // 新分类：用名称生成稳定 ID
      categoryMap.set(name, {
        id: `local-${name.toLowerCase().replace(/\s+/g, '-')}`,
        name,
        articleCount: 1,
        sources: ['local'],
      })
    }
  }
 
  return Array.from(categoryMap.values()).sort(
    (a, b) => b.articleCount - a.articleCount,
  )
}

// ✅ 好做法：页面组件只消费归一化结果
// app/[locale]/blog/_components/sidebar.tsx
 
interface SidebarProps {
  categories: UnifiedCategory[]
}
 
export function Sidebar({ categories }: SidebarProps) {
  return (
    <nav>
      {categories.map(cat => (
        <span key={cat.id}>
          {cat.name} ({cat.articleCount})
        </span>
      ))}
    </nav>
  )
}

// ❌ 坏做法：详情页自己处理来源判断和数据转换
// app/[locale]/blog/[slug]/page.tsx
 
export default async function ArticlePage({ params }: { params: { slug: string } }) {
  let article = null
 
  // 先查 CMS，失败再查本地——每次本地文章都要白跑一次接口
  try {
    article = await fetchCmsArticle(params.slug)
  } catch {
    article = await getLocalArticle(params.slug)
  }
 
  if (!article) return <div>Not found</div>
 
  return (
    <article>
      <h1>{article.title}</h1>
      {/* 数据结构不一致，渲染层被迫处理差异 */}
      <div className="author">
        {typeof article.author === 'object' ? (
          <img src={article.author.avatar} alt="" />
        ) : (
          <span>{article.author}</span>
        )}
      </div>
      {/* publishedAt 字段名在本地是 date，在 CMS 是 createdAt */}
      <time>{article.publishedAt || article.date || article.createdAt}</time>
      <div dangerouslySetInnerHTML={{ __html: article.content }} />
    </article>
  )
}

// ✅ 好做法：数据层统一来源识别和结构归一
// lib/content/article-resolver.ts
 
interface UnifiedArticle {
  slug: string
  title: string
  // 归一化后的作者信息，统一为对象
  author: {
    name: string
    avatar?: string
    bio?: string
  }
  // 统一的时间字段
  publishedAt: string
  // 统一的内容格式
  contentHtml: string
  // 来源标识
  source: 'cms' | 'local' | 'generated'
  // 原始数据保留，方便特殊场景
  raw: unknown
}
 
// 来源注册表：每种来源有自己的探测和读取逻辑
const resolvers: Array<{
  match: (slug: string) => Promise<boolean>
  read: (slug: string) => Promise<UnifiedArticle>
}> = [
  {
    // CMS 文章：slug 能匹配到接口返回的列表
    match: async (slug) => {
      const cmsSlugs = await getCmsArticleSlugs()
      return cmsSlugs.includes(slug)
    },
    read: async (slug) => {
      const raw = await fetchCmsArticle(slug)
      return {
        slug: raw.slug,
        title: raw.title,
        // CMS 返回的是对象，直接映射
        author: { name: raw.author.name, avatar: raw.author.avatar, bio: raw.author.bio },
        publishedAt: raw.createdAt,
        contentHtml: raw.body,
        source: 'cms',
        raw,
      }
    },
  },
  {
    // 本地 Markdown：文件系统上存在对应文件
    match: async (slug) => {
      const filePath = `content/articles/${slug}.md`
      return fileExists(filePath)
    },
    read: async (slug) => {
      const raw = await readLocalArticle(slug)
      return {
        slug,
        title: raw.frontmatter.title,
        // 本地只有字符串，包装成统一结构
        author: { name: raw.frontmatter.author || '匿名' },
        publishedAt: raw.frontmatter.date,
        contentHtml: raw.html,
        source: 'local',
        raw,
      }
    },
  },
]
 
export async function resolveArticle(slug: string): Promise<UnifiedArticle | null> {
  for (const resolver of resolvers) {
    // 按优先级逐个探测，命中即读取
    const matched = await resolver.match(slug)
    if (matched) {
      return resolver.read(slug)
    }
  }
  return null
}

// ✅ 好做法：详情页只做渲染，不做数据来源判断
// app/[locale]/blog/[slug]/page.tsx
 
export default async function ArticlePage({ params }: { params: { slug: string } }) {
  const article = await resolveArticle(params.slug)
 
  if (!article) notFound()
 
  return (
    <article>
      <h1>{article.title}</h1>
      {/* 所有来源的文章都保证有 author.name */}
      <div className="author">
        {article.author.avatar && <img src={article.author.avatar} alt="" />}
        <span>{article.author.name}</span>
      </div>
      {/* publishedAt 字段名统一，不需要 fallback 链 */}
      <time>{article.publishedAt}</time>
      <div dangerouslySetInnerHTML={{ __html: article.contentHtml }} />
    </article>
  )
}

// ❌ 坏做法：SEO 数据和页面内容从不同来源分别取
// app/[locale]/blog/[slug]/page.tsx
 
export async function generateMetadata({ params }: { params: { slug: string } }) {
  // 这里从缓存里取，可能和页面渲染时的数据不同步
  const cached = await getFromCache(`article:${params.slug}`)
 
  return {
    title: cached?.seoTitle || cached?.title,
    description: cached?.excerpt, // 列表页用 summary，这里用 excerpt，不一致
    openGraph: {
      images: [{ url: cached?.cover || '/default-og.png' }],
    },
  }
}
 
export default async function ArticlePage({ params }: { params: { slug: string } }) {
  // 这里从 resolveArticle 取，和 metadata 不是同一次数据读取
  const article = await resolveArticle(params.slug)
  // ...
}

// ✅ 好做法：SEO 数据和页面内容共享同一个数据读取结果
// app/[locale]/blog/[slug]/page.tsx
 
// 在 layout 或上层统一读取，数据向下传递
export async function generateMetadata({
  params,
}: {
  params: { slug: string }
}): Promise<Metadata> {
  // 和页面内容用同一个 resolveArticle
  const article = await resolveArticle(params.slug)
  if (!article) return {}
 
  return {
    title: article.title,
    // description 和 contentHtml 来自同一次数据读取
    description: extractExcerpt(article.contentHtml),
    openGraph: {
      // 封面数据也从统一结构取
      images: article.raw.cover ? [{ url: article.raw.cover.url }] : [],
      published_time: article.publishedAt,
      authors: [article.author.name],
    },
  }
}
 
export default async function ArticlePage({ params }: { params: { slug: string } }) {
  const article = await resolveArticle(params.slug)
  if (!article) notFound()
 
  // JSON-LD 也从同一个 article 对象生成，保证和可见内容一致
  const jsonLd = {
    '@context': 'https://schema.org',
    '@type': 'Article',
    headline: article.title,
    description: extractExcerpt(article.contentHtml),
    datePublished: article.publishedAt,
    author: { '@type': 'Person', name: article.author.name },
    image: article.raw.cover?.url,
  }
 
  return (
    <>
      <script
        type="application/ld+json"
        dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
      />
      <article>{/* ... */}</article>
    </>
  )
}