akisakye/useless-calculator-subtraction

减法服务

作为https://github.com/solvedevops/useless-calculator%E9%A1%B9%E7%9B%AE%E7%9A%84%E4%B8%80%E9%83%A8%E5%88%86%EF%BC%8C%E6%9C%AC%E5%BE%AE%E6%9C%8D%E5%8A%A1%E6%8F%90%E4%BE%9B%E5%87%8F%E6%B3%95%E8%BF%90%E7%AE%97%E5%8A%9F%E8%83%BD%E3%80%82

⚠️ 演示项目警告：本服务仅用于演示和训练目的，严禁在生产环境中使用。

🧮 核心功能

本服务提供简单的REST API，用于从第一个数字中减去第二个数字。

端点说明

• GET / - 执行减法操作
  • 参数：
    • first_number（浮点数，可选）：第一个数字（默认值：0）
    • second_number（浮点数，可选）：需减去的第二个数字（默认值：0）
  • 返回：包含运算结果的JSON对象
• GET /health - 健康检查端点
  • 返回：服务健康状态

🛠️ 技术栈

• FastAPI：现代Python Web框架
• Python 3.7+：编程语言
• Pydantic：数据验证与序列化
• Docker：容器化工具

🚀 快速开始

Docker方式

bash
# 构建镜像
docker build -t subtraction-service .

# 运行容器
docker run -p 5004:5004 \
  -e ENV_NAME=development \
  -e APP_NAME=subtraction-service \
  -e TELEMETRY_MODE=console \
  docker.xuanyuan.run/subtraction-service

手动部署

1. 安装依赖：

   bash
   pip install -r requirements.txt
   

2. 设置环境变量：

   bash
   export ENV_NAME=development
   export APP_NAME=subtraction-service
   export TELEMETRY_MODE=console
   

3. 启动服务：

   bash
   uvicorn app:app --host 0.0.0.0 --port 5004
   

⚙️ 配置说明

必填环境变量

遥测配置

遥测模式示例

bash
# 控制台输出（默认）
TELEMETRY_MODE=console

# 本地文件日志
TELEMETRY_MODE=local

# AWS CloudWatch
TELEMETRY_MODE=aws_cloudwatch

# Azure Monitor
TELEMETRY_MODE=azure_monitor

# 多输出
TELEMETRY_MODE=console,local

📊 API文档

减法操作示例

请求：

bash
GET /?first_number=10&second_number=3

响应：

json
{
  "result": 7.0,
  "operation": "subtraction",
  "first_number": 10.0,
  "second_number": 3.0
}

健康检查示例

请求：

bash
GET /health

响应：

json
{
  "status": "healthy",
  "service": "subtraction-service"
}

交互式文档

服务运行时可访问：

• Swagger UI：http://localhost:5004/docs
• ReDoc：http://localhost:5004/redoc

📈 监控与可观测性

结构化遥测

服务提供全面的可观测性：

• 日志：操作事件与错误记录
• 指标：包含响应时间的性能数据
• 追踪：带操作细节的请求追踪

云集成标签

• :latest：仅支持控制台和本地存储
• :aws-logs：支持CloudWatch配置（需IAM权限）
• :azure-logs：支持Azure Monitor（需连接字符串）

🧪 测试

运行测试

bash
# 安装测试依赖
pip install pytest httpx

# 执行测试
pytest test_app.py -v

测试示例

bash
# 基础减法测试
curl "http://localhost:5004/?first_number=10&second_number=3"

# 负数结果测试
curl "http://localhost:5004/?first_number=5&second_number=8"

# 健康检查测试
curl "http://localhost:5004/health"

🔧 开发

项目结构

subtraction-service/
├── app.py              # FastAPI应用
├── telemetry.py        # 遥测与日志模块
├── test_app.py         # 单元测试
├── requirements.txt    # Python依赖
├── Dockerfile         # 容器配置
└── README.md          # 说明文档

关键特性

• ✅ 输入验证与类型转换
• ✅ 全面错误处理
• ✅ 支持负数结果
• ✅ 健康检查端点
• ✅ 结构化日志与遥测
• ✅ API文档
• ✅ 单元测试
• ✅ Docker支持

🔐 安全说明

• 不处理或记录敏感数据
• 输入验证防止基础注入***
• 遥测遵循安全日志规范
• 健康检查不暴露敏感信息

📚 相关服务

• https://github.com/solvedevops/useless-calculator - Web界面与协调器
• https://github.com/solvedevops/addition-service - 处理加法操作
• https://github.com/solvedevops/multiplication-service - 处理乘法操作
• https://github.com/solvedevops/division-service - 处理除法操作

⚖️ 许可证

本项目仅用于教育和演示目的，在演示环境中使用需自行承担风险。

🤝 贡献

本项目为训练用演示项目，欢迎分叉和实验！