databricks-app-apx

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Databricks APX Application

Databricks APX应用程序

Build full-stack Databricks applications using APX framework (FastAPI + React).

使用APX框架（FastAPI + React）构建全栈Databricks应用程序。

Trigger Conditions

触发条件

Invoke when user requests:

"Databricks app" or "Databricks application"
Full-stack app for Databricks without specifying framework
Mentions APX framework

Do NOT invoke if user specifies: Streamlit, Dash, Node.js, Shiny, Gradio, Flask, or other frameworks.

当用户请求以下内容时触发:

"Databricks app" 或 "Databricks application"
未指定框架的Databricks全栈应用
提及APX框架

当用户指定以下框架时，请勿触发：Streamlit、Dash、Node.js、Shiny、Gradio、Flask或其他框架。

Prerequisites Check

前提条件检查

Option A) Repository configured for use with APX. 1.. Verify APX MCP available:

mcp-cli tools | grep apx

2. Verify shadcn MCP available:

mcp-cli tools | grep shadcn

3. Confirm APX project (check

pyproject.toml

)

Option B) Install APX

Verify uv available or prompt for install. On Mac, suggest:
```
brew install uv
```
.
Verify bun available or prompt for install. On Mac, suggest:

brew tap oven-sh/bun
brew install bun

Verify git available or prompt for install.
Run APX setup commands:

uvx --from git+https://github.com/databricks-solutions/apx.git apx init

选项A）已配置为使用APX的代码仓库。

验证APX MCP是否可用：
```
mcp-cli tools | grep apx
```
验证shadcn MCP是否可用：
```
mcp-cli tools | grep shadcn
```
确认APX项目（检查
```
pyproject.toml
```
）

选项B）安装APX

验证uv是否可用，若不可用则提示安装。在Mac上，建议：
```
brew install uv
```
。
验证bun是否可用，若不可用则提示安装。在Mac上，建议：

brew tap oven-sh/bun
brew install bun

验证git是否可用，若不可用则提示安装。
运行APX初始化命令：

uvx --from git+https://github.com/databricks-solutions/apx.git apx init

Workflow Overview

工作流概述

Total time: 55-70 minutes

Initialize (5 min) - Start servers, create todos
Backend (15-20 min) - Models + routes with mock data
Frontend (20-25 min) - Components + pages
Test (5-10 min) - Type check + manual verification
Document (10 min) - README + code structure guide

总耗时：55-70分钟

初始化（5分钟）- 启动服务器，创建任务清单
后端开发（15-20分钟）- 模型 + 模拟数据路由
前端开发（20-25分钟）- 组件 + 页面
测试（5-10分钟）- 类型检查 + 手动验证
文档编写（10分钟）- README + 代码结构指南

Phase 1: Initialize

阶段1：初始化

bash

undefined

bash

undefined

Start APX development server

启动APX开发服务器

mcp-cli call apx/start '{}' mcp-cli call apx/status '{}'


Create TodoWrite with tasks:
- Start servers ✓
- Design models
- Create API routes
- Add UI components
- Create pages
- Test & document

mcp-cli call apx/start '{}' mcp-cli call apx/status '{}'


创建包含以下任务的TodoWrite：
- 启动服务器 ✓
- 设计模型
- 创建API路由
- 添加UI组件
- 创建页面
- 测试与文档编写

Phase 2: Backend Development

阶段2：后端开发

Create Pydantic Models

创建Pydantic模型

src/{app_name}/backend/models.py

Follow 3-model pattern:

```
EntityIn
```
- Input validation
```
EntityOut
```
- Complete output with computed fields
```
EntityListOut
```
- Performance-optimized summary

See backend-patterns.md for complete code templates.

在

src/{app_name}/backend/models.py

中：

遵循三模型模式:

```
EntityIn
```
- 输入验证
```
EntityOut
```
- 包含计算字段的完整输出
```
EntityListOut
```
- 性能优化的摘要

查看[backend-patterns.md]获取完整代码模板。

Create API Routes

创建API路由

src/{app_name}/backend/router.py

Critical requirements:

Always include
```
response_model
```
(enables OpenAPI generation)
Always include
```
operation_id
```
(becomes frontend hook name)
Use naming pattern:
```
listX
```
,
```
getX
```
,
```
createX
```
,
```
updateX
```
,
```
deleteX
```
Initialize 3-4 mock data samples for testing

See backend-patterns.md for complete CRUD templates.

在

src/{app_name}/backend/router.py

中：

关键要求:

始终包含
```
response_model
```
（支持OpenAPI生成）
始终包含
```
operation_id
```
（将成为前端钩子名称）
使用命名模式：
```
listX
```
,
```
getX
```
,
```
createX
```
,
```
updateX
```
,
```
deleteX
```
初始化3-4个模拟数据样本用于测试

查看[backend-patterns.md]获取完整的CRUD模板。

Type Check

类型检查

bash

mcp-cli call apx/dev_check '{}'

Fix any Python type errors reported by basedpyright.

bash

mcp-cli call apx/dev_check '{}'

修复basedpyright报告的所有Python类型错误。

Phase 3: Frontend Development

阶段3：前端开发

Wait 5-10 seconds after backend changes for OpenAPI client regeneration.

后端更改后等待5-10秒，以便重新生成OpenAPI客户端。

Add UI Components

添加UI组件

bash

undefined

bash

undefined

Get shadcn add command

获取shadcn添加命令

mcp-cli call shadcn/get_add_command_for_items '{ "items": ["@shadcn/button", "@shadcn/card", "@shadcn/table", "@shadcn/badge", "@shadcn/select", "@shadcn/skeleton"] }'


Run the command from project root with `--yes` flag.

mcp-cli call shadcn/get_add_command_for_items '{ "items": ["@shadcn/button", "@shadcn/card", "@shadcn/table", "@shadcn/badge", "@shadcn/select", "@shadcn/skeleton"] }'


在项目根目录运行带`--yes`标志的命令。

Create Pages

创建页面

List page:

src/{app_name}/ui/routes/_sidebar/{entity}.tsx

Table view with all entities
Suspense boundaries with skeleton fallback
Formatted data (currency, dates, status colors)

Detail page:

src/{app_name}/ui/routes/_sidebar/{entity}.$id.tsx

Complete entity view with cards
Update/delete mutations
Back navigation

See frontend-patterns.md for complete page templates.

列表页面：

src/{app_name}/ui/routes/_sidebar/{entity}.tsx

显示所有实体的表格视图
带骨架屏占位的Suspense边界
格式化数据（货币、日期、状态颜色）

详情页面：

src/{app_name}/ui/routes/_sidebar/{entity}.$id.tsx

使用卡片展示完整实体信息
更新/删除操作
返回导航

查看[frontend-patterns.md]获取完整页面模板。

Update Navigation

更新导航

src/{app_name}/ui/routes/_sidebar/route.tsx

, add new item to

navItems

array.

在

src/{app_name}/ui/routes/_sidebar/route.tsx

中，将新条目添加到

navItems

数组。

Phase 4: Testing

阶段4：测试

bash

undefined

bash

undefined

Type check both backend and frontend

同时检查后端和前端的类型

mcp-cli call apx/dev_check '{}'

Test API endpoints

测试API端点

curl http://localhost:8000/api/{entities} | jq . curl http://localhost:8000/api/{entities}/{id} | jq .

Get frontend URL

获取前端URL

mcp-cli call apx/get_frontend_url '{}'


Manually verify in browser:
- List page displays data
- Detail page shows complete info
- Mutations work (update, delete)
- Loading states work (skeletons)
- Browser console errors are automatically captured in APX dev logs

mcp-cli call apx/get_frontend_url '{}'


在浏览器中手动验证：
- 列表页面显示数据
- 详情页面显示完整信息
- 操作功能正常（更新、删除）
- 加载状态正常（骨架屏显示）
- 浏览器控制台错误会自动捕获到APX开发日志中

Phase 5: Deployment & Monitoring

阶段5：部署与监控

Deploy to Databricks

部署到Databricks

Use DABs to deploy your APX application to Databricks. See the

asset-bundles

skill for complete deployment guidance.

使用DABs将你的APX应用部署到Databricks。查看

asset-bundles

技能获取完整部署指南。

Monitor Application Logs

监控应用日志

Automated log checking with APX MCP:

The APX MCP server can automatically check deployed application logs. Simply ask: "Please check the deployed app logs for <app-name>"

The APX MCP will retrieve logs and identify issues automatically, including:

Deployment status and errors
Runtime exceptions and stack traces
Both
```
[SYSTEM]
```
(deployment) and
```
[APP]
```
(application) logs
Browser console errors (now included in APX dev logs)

Manual log checking (reference):

For direct CLI access:

bash

databricks apps logs <app-name> --profile <profile-name>

Key patterns to look for:

✅
```
Deployment successful
```
- App deployed correctly
✅
```
App started successfully
```
- Application is running
❌
```
Error:
```
- Check stack traces for issues

使用APX MCP自动检查日志:

APX MCP服务器可以自动检查已部署应用的日志。只需询问： "请检查<app-name>已部署应用的日志"

APX MCP将检索日志并自动识别问题，包括：

部署状态与错误
运行时异常与堆栈跟踪
```
[SYSTEM]
```
（部署）和
```
[APP]
```
（应用）两类日志
浏览器控制台错误（现已包含在APX开发日志中）

手动检查日志（参考）:

如需直接通过CLI访问：

bash

databricks apps logs <app-name> --profile <profile-name>

需要关注的关键模式:

✅
```
Deployment successful
```
- 应用部署成功
✅
```
App started successfully
```
- 应用正在运行
❌
```
Error:
```
- 检查堆栈跟踪以定位问题

Phase 6: Documentation

阶段6：文档编写

Create two markdown files:

README.md:

Features overview
Technology stack
How app was created (AI tools + MCP servers used)
Application architecture
Getting started instructions
API documentation
Development workflow

CODE_STRUCTURE.md:

Directory structure explanation
Backend structure (models, routes, patterns)
Frontend structure (routes, components, hooks)
Auto-generated files warnings
Guide for adding new features
Best practices
Common patterns
Troubleshooting guide

创建两个Markdown文件：

README.md:

功能概述
技术栈
应用创建方式（使用的AI工具 + MCP服务器）
应用架构
快速开始指南
API文档
开发工作流

CODE_STRUCTURE.md:

目录结构说明
后端结构（模型、路由、模式）
前端结构（路由、组件、钩子）
自动生成文件警告
新增功能指南
最佳实践
常见模式
故障排除指南

Key Patterns

关键模式

Backend

后端

3-model pattern: Separate In, Out, and ListOut models
operation_id naming:
```
listEntities
```
→
```
useListEntities()
```
Type hints everywhere: Enable validation and IDE support

三模型模式：分离In、Out和ListOut模型
operation_id命名：
```
listEntities
```
→
```
useListEntities()
```
处处使用类型提示：启用验证与IDE支持

Frontend

前端

Suspense hooks:
```
useXSuspense(selector())
```
Suspense boundaries: Always provide skeleton fallback
Formatters: Currency, dates, status colors
Never edit:
```
lib/api.ts
```
or
```
types/routeTree.gen.ts
```

Suspense钩子：
```
useXSuspense(selector())
```
Suspense边界：始终提供骨架屏占位
格式化工具：货币、日期、状态颜色
请勿编辑：
```
lib/api.ts
```
或
```
types/routeTree.gen.ts
```

Success Criteria

成功标准

Type checking passes (
```
apx dev check
```
succeeds)
API endpoints return correct data (curl verification)
Frontend displays and mutates data correctly
Loading states work (skeletons display)
Documentation complete

类型检查通过（
```
apx dev check
```
执行成功）
API端点返回正确数据（curl验证）
前端正确显示并修改数据
加载状态正常（骨架屏显示）
文档编写完成

Common Issues

常见问题

Deployed app not working: Ask to check deployed app logs (APX MCP will automatically retrieve and analyze them) or manually use

databricks apps logs <app-name>

Python type errors: Use explicit casting for dict access, check Optional fields TypeScript errors: Wait for OpenAPI regen, verify hook names match operation_ids OpenAPI not updating: Check watcher status with

apx dev status

, restart if needed Components not added: Run shadcn from project root with

--yes

flag

已部署应用无法工作：请求检查已部署应用的日志（APX MCP将自动检索并分析），或手动使用

databricks apps logs <app-name>

Python类型错误：对字典访问使用显式类型转换，检查可选字段 TypeScript错误：等待OpenAPI重新生成，验证钩子名称与operation_id匹配 OpenAPI未更新：使用

apx dev status

检查监视器状态，如有需要重启 组件未添加：在项目根目录运行带

--yes

标志的shadcn命令

Reference Materials

参考资料

backend-patterns.md - Complete backend code templates
frontend-patterns.md - Complete frontend page templates
best-practices.md - Best practices, anti-patterns, debugging

Read these files only when actively writing that type of code or debugging issues.

[backend-patterns.md] - 完整后端代码模板
[frontend-patterns.md] - 完整前端页面模板
[best-practices.md] - 最佳实践、反模式、调试指南

仅在编写对应代码或调试问题时阅读这些文件。