lz-stash

Appearance

🔧 服务系统 ​

lzt 提供了完整的微服务解决方案，专注于企业级应用开发和高性能服务架构。

📊 Ledger 账本服务 ​

基于 gRPC 构建的现代化财务管理微服务，采用领域驱动设计 (DDD) 和 Clean Architecture 架构模式。

🎯 核心功能 ​

🏗️ 技术架构 ​

分层架构设计 ​

  • 接口层 - gRPC API 和 HTTP Gateway
  • 应用层 - 业务服务和用例实现
  • 领域层 - 核心业务逻辑和实体
  • 基础设施层 - 数据持久化和外部集成

核心技术栈 ​

  • API 定义: Protocol Buffers 3.0
  • RPC 通信: gRPC with HTTP/2
  • 数据库: GORM + MySQL/PostgreSQL/SQLite
  • 依赖注入: Wire 自动化依赖注入
  • 配置管理: Viper 多层配置
  • 日志记录: 结构化日志 (JSON)

📡 完整的 API 服务 ​

gRPC 服务群 ​

  • LedgerService - 账本生命周期管理
  • TransactionService - 交易记录处理
  • TagService - 标签分类管理
  • BudgetService - 预算计划管理
  • AnalyticsService - 统计分析服务

HTTP REST API ​

通过 gRPC Gateway 自动生成 RESTful API：

bash
# 账本管理
GET    /api/v1/ledgers
POST   /api/v1/ledgers
GET    /api/v1/ledgers/{id}
PATCH  /api/v1/ledgers/{id}
DELETE /api/v1/ledgers/{id}

# 交易记录
GET    /api/v1/ledgers/{ledger_id}/transactions
POST   /api/v1/ledgers/{ledger_id}/transactions
GET    /api/v1/transactions/{id}
PATCH  /api/v1/transactions/{id}
DELETE /api/v1/transactions/{id}

# 统计分析
GET    /api/v1/ledgers/{ledger_id}/analytics
GET    /api/v1/ledgers/{ledger_id}/reports
GET    /api/v1/ledgers/{ledger_id}/trends

🌐 多语言 SDK 支持 ​

自动化 SDK 生成 ​

使用 Buf CLI 自动生成多语言客户端 SDK：

bash
# 生成 Node.js/TypeScript SDK
buf generate --template buf.gen.nodejs.yaml

# 生成 PHP SDK  
buf generate --template buf.gen.php.yaml

# 生成 Python SDK
buf generate --template buf.gen.python.yaml

# 生成 Go SDK
buf generate --template buf.gen.yaml

SDK 使用示例 ​

Node.js/TypeScript:

typescript
import { LedgerServiceClient } from '@lzt/ledger-sdk';

const client = new LedgerServiceClient('localhost:8080');
const response = await client.createTransaction({
  ledgerId: 'ledger-001',
  type: 'TRANSACTION_TYPE_EXPENSE',
  description: '午餐',
  amount: { amount: 3500, currency: 'CURRENCY_CNY' }
});

Python:

python
import grpc
from lz_stash.ledger.v1 import ledger_pb2_grpc, ledger_pb2

channel = grpc.insecure_channel('localhost:8080')
client = ledger_pb2_grpc.LedgerServiceStub(channel)

response = client.CreateTransaction(
    ledger_pb2.CreateTransactionRequest(
        ledger_id='ledger-001',
        type=ledger_pb2.TRANSACTION_TYPE_EXPENSE,
        description='午餐',
        amount=ledger_pb2.Money(amount=3500, currency=ledger_pb2.CURRENCY_CNY)
    )
)

💾 数据持久化 ​

数据库设计 ​

  • 多数据库支持 - SQLite (开发) / MySQL (生产) / PostgreSQL (企业)
  • ORM 框架 - GORM v2 with 自动迁移
  • 关系模型 - 完整的外键约束和索引优化
  • 事务支持 - ACID 特性和数据一致性保证

性能优化 ​

  • 连接池管理 - 可配置的数据库连接池
  • 查询优化 - 索引策略和查询性能调优
  • 批量操作 - 高效的批量插入和更新
  • 缓存策略 - 查询结果缓存和失效策略

📈 运维和监控 ​

服务监控 ​

  • 健康检查 - gRPC 健康检查和存活探针
  • 指标收集 - Prometheus 指标导出
  • 链路追踪 - 分布式追踪和性能分析
  • 日志聚合 - 结构化日志和查询

部署方案 ​

  • 容器化 - Docker 镜像和 Kubernetes 部署
  • 配置管理 - 环境变量和配置文件管理
  • 服务发现 - 微服务注册和发现
  • 负载均衡 - 服务级负载均衡和故障转移

🚀 快速开始 ​

本地开发环境 ​

bash
# 1. 初始化数据库和配置
lzt ledger init

# 2. 启动 gRPC 服务
lzt ledger server --port 8080

# 3. 验证服务状态
grpcurl -plaintext localhost:8080 list

Docker 部署 ​

bash
# 构建服务镜像
docker build -t lzt:latest .

# 启动服务容器
docker run -p 8080:8080 \
  -e DB_HOST=mysql \
  -e DB_USER=ledger \
  -e DB_PASSWORD=secret \
  lzt:latest ledger server

📚 深入学习 ​

架构设计 ​

部署运维 ​

技术深度 ​

🎯 应用场景 ​

个人财务管理 ​

  • 个人记账应用 - 日常收支记录和预算管理
  • 投资组合跟踪 - 多账户资产管理和收益分析
  • 家庭理财规划 - 多成员协作的家庭账本

企业财务系统 ​

  • 小微企业财务 - 简单易用的企业账本管理
  • 项目成本跟踪 - 基于标签的项目支出统计
  • 部门预算管理 - 多部门预算制定和监控

系统集成 ​

  • 微服务架构 - 作为财务微服务集成到现有系统
  • API 网关集成 - 通过网关暴露 HTTP API
  • 数据分析平台 - 财务数据的 ETL 和分析

💡 开发建议: 建议先了解系统架构和 API 设计，然后根据具体需求选择对应的 SDK 进行集成开发。

基于 MIT 许可证发布

Copyright © 2024 lz-stash 项目