前端页面：TanStack Start
后端 HTTP/API：Hono
长期 API 合约：oRPC
部署平台：Cloudflare Workers

保存用户设置
提交表单
读取当前页面 dashboard 数据

Web
微信小程序
Tauri 桌面端
移动 App
AI Agent
第三方脚本
开放 API

前端不知道接口要传什么
接口返回值靠人脑记
错误格式不统一
API 文档没人维护
小程序/App/Agent 又要重新对接

Hono 负责 HTTP 边界
oRPC 负责 API 合约

我的 Web 前端 调用 我的 Hono 后端

Web
小程序
App
Tauri
AI Agent
外部脚本
第三方系统

API 文档
OpenAPI
错误格式
多端调用
长期合约
业务模块化

createPost({
  title: string
  content: string
})

{
  id: string
  title: string
  content: string
  createdAt: string
}

// db/posts.ts
export async function insertPost(input: {
  title: string
  content: string
}) {
  return {
    id: crypto.randomUUID(),
    title: input.title,
    content: input.content,
    createdAt: new Date().toISOString(),
  }
}

// app/server/posts.ts
import { createServerFn } from '@tanstack/react-start'
import { z } from 'zod'
import { insertPost } from './db/posts'

const CreatePostSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
})

export const createPost = createServerFn({ method: 'POST' })
  .validator((data) => CreatePostSchema.parse(data))
  .handler(async ({ data }) => {
    const post = await insertPost(data)
    return post
  })

// app/routes/posts/new.tsx
import { useState } from 'react'
import { createPost } from '@/server/posts'

export default function NewPostPage() {
  const [title, setTitle] = useState('')
  const [content, setContent] = useState('')

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault()

    const post = await createPost({
      data: {
        title,
        content,
      },
    })

    console.log('created post:', post)
  }

  return (
    <form onSubmit={onSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="标题"
      />

      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="内容"
      />

      <button type="submit">创建文章</button>
    </form>
  )
}

页面内部表单
Dashboard 操作
快速 MVP
不需要给小程序/App/Agent 调用

最少代码
最快开发
类型体验好

不是正式 API 合约
多端复用不自然

// server/app.ts
import { Hono } from 'hono'
import { z } from 'zod'
import { zValidator } from '@hono/zod-validator'
import { insertPost } from './db/posts'

const app = new Hono()

const CreatePostSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
})

app.post(
  '/api/posts',
  zValidator('json', CreatePostSchema),
  async (c) => {
    const input = c.req.valid('json')
    const post = await insertPost(input)

    return c.json(post)
  },
)

export default app

// app/routes/posts/new.tsx
import { useState } from 'react'

type Post = {
  id: string
  title: string
  content: string
  createdAt: string
}

export default function NewPostPage() {
  const [title, setTitle] = useState('')
  const [content, setContent] = useState('')

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault()

    const res = await fetch('/api/posts', {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
      },
      body: JSON.stringify({
        title,
        content,
      }),
    })

    if (!res.ok) {
      throw new Error('创建文章失败')
    }

    const post = (await res.json()) as Post

    console.log('created post:', post)
  }

  return (
    <form onSubmit={onSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="标题"
      />

      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="内容"
      />

      <button type="submit">创建文章</button>
    </form>
  )
}

Webhook
支付回调
AI 接口
上传接口
后台 API
标准 HTTP 服务

边界清楚
标准 HTTP
Cloudflare 友好
任何客户端都能调用

前端类型需要自己维护
返回值容易靠人脑记
错误格式容易不统一

// rpc/schemas/post.ts
import { z } from 'zod'

export const CreatePostSchema = z.object({
  title: z.string().min(1),
  content: z.string().min(1),
})

export const PostSchema = z.object({
  id: z.string(),
  title: z.string(),
  content: z.string(),
  createdAt: z.string(),
})

// rpc/router.ts
import { os } from '@orpc/server'
import { insertPost } from '../server/db/posts'
import { CreatePostSchema, PostSchema } from './schemas/post'

export const postsRouter = {
  create: os
    .input(CreatePostSchema)
    .output(PostSchema)
    .handler(async ({ input }) => {
      const post = await insertPost(input)
      return post
    }),
}

export const appRouter = {
  posts: postsRouter,
}

export type AppRouter = typeof appRouter

// server/app.ts
import { Hono } from 'hono'
import { RPCHandler } from '@orpc/server/fetch'
import { appRouter } from '../rpc/router'

const app = new Hono()

const handler = new RPCHandler(appRouter)

app.use('/rpc/*', async (c, next) => {
  const { matched, response } = await handler.handle(c.req.raw, {
    prefix: '/rpc',
    context: {
      // user: c.get('user'),
      // env: c.env,
    },
  })

  if (matched) {
    return response
  }

  await next()
})

export default app

// rpc/client.ts
import { createORPCClient } from '@orpc/client'
import { RPCLink } from '@orpc/client/fetch'
import type { RouterClient } from '@orpc/server'
import type { AppRouter } from './router'

const link = new RPCLink({
  url: '/rpc',
})

export const client: RouterClient<AppRouter> = createORPCClient(link)

// app/routes/posts/new.tsx
import { useState } from 'react'
import { client } from '@/rpc/client'

export default function NewPostPage() {
  const [title, setTitle] = useState('')
  const [content, setContent] = useState('')

  async function onSubmit(e: React.FormEvent) {
    e.preventDefault()

    const post = await client.posts.create({
      title,
      content,
    })

    console.log('created post:', post)
  }

  return (
    <form onSubmit={onSubmit}>
      <input
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        placeholder="标题"
      />

      <textarea
        value={content}
        onChange={(e) => setContent(e.target.value)}
        placeholder="内容"
      />

      <button type="submit">创建文章</button>
    </form>
  )
}

Web + 小程序 + App
Tauri 桌面端
AI Agent 调用
开放 API
长期业务系统
需要 API 文档
需要统一错误格式

前端调用像本地函数
输入输出类型自动对齐
API 语义清晰
未来更适合多端

多一层抽象
早期小项目可能显得复杂

apps/web
  TanStack Start
  TanStack Router
  React
  Tailwind / shadcn

server
  Hono
  middleware
  auth
  webhook
  api boundary

rpc
  oRPC router
  schemas
  procedures
  client

db
  Drizzle
  D1 / Postgres

Web 页面
  ↓
TanStack Start
  ↓
页面私有逻辑：Server Function
  ↓
多端业务逻辑：oRPC Client
  ↓
Hono /rpc/*
  ↓
oRPC Router
  ↓
Drizzle / D1 / Postgres

TanStack 比 Next.js 好
Hono 比 Next.js 好
oRPC 比 Hono 好