Instatic代码风格指南命名规范与格式【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/InstaticInstatic是一个现代化的自托管可视化CMS系统采用TypeScript编写并运行在Bun运行时上。本文将详细介绍Instatic项目的代码风格指南包括命名规范、文件组织、类型安全和架构约定帮助开发者快速掌握这个项目的编码标准。目录项目架构概览命名规范类型安全与TypeBoxReact组件与状态管理CSS与设计系统数据库与迁移错误处理模式工具与验证项目架构概览Instatic采用单一代码库架构所有功能都集成在一个Bun服务器中。前端使用React 19并启用React Compiler后端使用Bun.serve构建的自定义路由器。项目严格遵循验证然后信任的原则所有无类型边界都通过TypeBox进行验证。命名规范文件与目录命名kebab-case命名所有文件和目录名使用短横线连接例如api-client.ts、typebox-helpers.ts组件文件React组件文件使用大驼峰命名如Button.tsx对应的CSS模块文件为Button.module.css测试文件测试文件使用.test.ts后缀如button-primitive-usage.test.ts模块组织src/core/- 核心引擎代码src/admin/- 管理界面React应用src/ui/- 共享UI组件src/modules/- 内置模块server/- 服务器端代码变量与函数命名camelCase命名变量和函数使用小驼峰命名法布尔变量以is、has、can等前缀开头如isLoading、hasPermissionTypeBox模式模式变量以Schema结尾如UserSchema、PageTreeSchema类型推断使用Statictypeof Schema获取类型而不是单独定义接口// ✅ 正确模式作为唯一来源 const UserSchema Type.Object({ id: Type.String(), email: Type.String({ format: email }) }) type User Statictypeof UserSchema // ❌ 错误不要定义重复的接口 interface User { id: string email: string }常量命名UPPER_SNAKE_CASE配置常量、枚举值使用全大写蛇形命名JSON列命名数据库中的JSON列必须以_json结尾如settings_json类型安全与TypeBoxInstatic完全采用TypeBox作为类型验证的单一来源禁止使用Zod。所有无类型边界都必须通过TypeBox模式进行验证。边界验证模式// HTTP请求边界 const body parseValue(RequestBodySchema, await req.json()) // JSON解析边界 const data safeParseJson(rawJson, DataSchema) // 软边界回退 const prefs parseJsonWithFallback( localStorage.getItem(prefs) ?? , PreferencesSchema, DEFAULT_PREFERENCES )HTTP客户端统一接口所有浏览器到服务器的调用都通过apiRequest函数进行import { apiRequest } from core/http // 标准调用方式 const result await apiRequest(/api/users, { method: POST, body: { email, password }, schema: UserSchema })React组件与状态管理组件编写规范无手动记忆化React Compiler已启用禁止手动使用useMemo、useCallback、memo()状态突变模式使用draft-mutation风格set((s) { s.x … })UI组件使用所有交互控件必须使用src/ui/components/中的原始组件// ✅ 正确让编译器处理记忆化 function UserList({ users }: { users: User[] }) { return users.map(user UserCard key{user.id} user{user} /) } // ❌ 错误不要手动记忆化 const memoizedUsers useMemo(() users.map(...), [users])三个例外情况只有以下三种情况可以保留记忆化依赖数组中的函数当函数被用在useEffect依赖数组中时热路径组件在列表渲染的递归组件等性能关键路径上编译器无法编译使用use no memo指令标记CSS与设计系统设计令牌原则Instatic采用两层色彩模型基础层为无色系色彩层用于标识和状态。无色基础表面、边框、默认文本使用中性色语义色彩使用--accent-1到--accent-10表示分类标识状态色彩使用--editor-danger、--editor-warning等表示状态CSS模块规则仅CSS模块禁止使用Tailwind工具类无硬编码颜色所有颜色必须来自src/styles/globals.css中的设计令牌无CSS变量回退禁止使用var(--name, fallback)语法camelCase类名CSS模块中的类名使用小驼峰命名/* ✅ 正确使用设计令牌 */ .button { background-color: var(--bg-surface-2); border-radius: var(--radius); } /* ❌ 错误硬编码颜色 */ .button { background-color: #1b1b1b; /* 禁止 */ border-radius: 6px; /* 禁止 */ }边框半径规范--editor-radius-sm(3px)紧凑徽章--editor-radius(6px)默认编辑器控件--panel-radius(12px)浮动面板16px卡片圆角数据库与迁移方言无关的SQL所有数据库操作必须使用ANSI标准SQL// ✅ 正确方言无关 db.query(SELECT * FROM users WHERE id ?, [id]) // ❌ 错误Postgres特定语法 db.query(SELECT * FROM users WHERE id $1, [id])迁移管理双向迁移所有迁移必须在migrations-pg.ts和migrations-sqlite.ts中都有对应版本仅添加不删除迁移必须是增量的不能删除已有列或表相同ID两个文件中的迁移ID必须一致错误处理模式错误边界所有错误处理遵循验证然后信任的原则// 硬边界验证失败则抛出 try { const body parseValue(RequestBodySchema, await req.json()) } catch (err) { throw new ApiError(Invalid request, 400) } // 软边界验证失败则回退 const settings parseJsonWithFallback( localStorage.getItem(settings), SettingsSchema, DEFAULT_SETTINGS )用户可见错误操作失败通过全局toast系统显示import { pushToast } from ui/components/Toast try { await saveChanges() } catch (err) { pushToast({ kind: error, title: 保存失败, body: getErrorMessage(err, 未知错误) }) }工具与验证开发工具Bun运行时使用Bun而不是Node.js类型检查bun run build运行tsc -b vite build代码质量bun run lint执行ESLint检查架构测试bun test运行包括架构门控测试架构门控测试Instatic使用架构测试确保代码质量css-token-policy.test.ts禁止硬编码颜色no-tailwind-deps.test.ts禁止Tailwind依赖db-json-column-naming.test.tsJSON列命名规范boundary-validation.test.ts边界验证要求总结Instatic的代码风格指南强调一致性、类型安全和架构清晰度。通过严格的命名规范、统一的TypeBox验证、React Compiler的自动记忆化和设计令牌系统项目保持了高度的可维护性和可扩展性。关键要点TypeBox作为单一来源所有类型定义都来自模式无手动记忆化信任React Compiler设计令牌驱动CSS中无硬编码值方言无关的SQL支持Postgres和SQLite验证然后信任所有边界都有类型验证遵循这些规范将确保您的代码与Instatic的架构保持一致并能够通过所有的门控测试。【免费下载链接】InstaticInstatic is a modern self-hosted visual CMS - get it running in 1 minute项目地址: https://gitcode.com/GitHub_Trending/in/Instatic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
