feat(api): unify API naming to snake_case with CamelCaseJSONField

duanhongyi · duanhongyi · commit 48c6062659b9 · 2026-08-09T21:58:38.000+08:00
Add CamelCaseJSONField serializer field that converts between snake_case
(API layer) and camelCase (DB/K8s layer). Applied to RouteSerializer.rules,
ConfigSerializer.healthcheck/lifecycle, AddonInstanceSerializer.parameters,
AddonClassSerializer.plans, VolumeSerializer.parameters, and new
PodDetailSerializer/DeploymentDetailSerializer for describe endpoints.

- Remove id from Gateway/Route serializers, uuid from AddonInstance
- Add PodDetailSerializer and DeploymentDetailSerializer with CamelCaseJSONField
- Unify ServiceSerializer (list output + input validation in one class)
- Change AddonClassSerializer from BaseSerializer to Serializer with source
- describe_pod output keys changed to snake_case (last_state, restart_count)
- CLI output now uses snake_case: backend_refs, liveness_probe, post_start
- DB/K8s storage unchanged (camelCase), Python code unchanged
- Update AGENTS.md with CamelCaseJSONField documentation and conventions
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,5 +1,9 @@
 # Drycc Controller — Agent Instructions
 
+> **When you change code patterns, conventions, or architecture, update this file
+> in the same commit.** AGENTS.md is the single source of truth for project
+> conventions — if it's stale, the next agent will follow wrong patterns.
+
 ## Project Structure
 
 ```
@@ -201,6 +205,52 @@ class MyModelSerializer(serializers.ModelSerializer):
         read_only_fields = ['uuid', 'created', 'updated']
 ```
 
+### Naming Convention: snake_case API + CamelCaseJSONField
+
+The API uses **snake_case** for all field names. K8s data stored in JSONFields
+uses camelCase internally (matching K8s API conventions), but is exposed as
+snake_case in API responses.
+
+**`CamelCaseJSONField`** (in `api/serializers/__init__.py`, extends `JSONFieldSerializer`):
+- **Input** (`to_internal_value`): converts snake_case keys to camelCase before
+  validation and DB storage. Both snake_case and camelCase input are accepted.
+- **Output** (`to_representation`): converts camelCase keys to snake_case for API
+  responses.
+- **DB storage**: camelCase (Python code and K8s API calls use camelCase unchanged).
+- Conversion functions (`camelize`, `underscoreize`, etc.) live in `api/utils.py`.
+
+Use `CamelCaseJSONField` for any JSONField that contains K8s camelCase data:
+
+```python
+class RouteSerializer(serializers.ModelSerializer):
+    rules = CamelCaseJSONField(convert_to_str=False, required=True)
+    parent_refs = serializers.JSONField(required=True)  # single-word keys, no conversion needed
+```
+
+For serializers that read from K8s CRD/API (not Django models), use `Serializer`
+with `source` + `CamelCaseJSONField`:
+
+```python
+class AddonClassSerializer(serializers.Serializer):
+    name = serializers.CharField(source='metadata.name', required=False)
+    plans = CamelCaseJSONField(source='spec.plans', required=False)
+```
+
+**When to use CamelCaseJSONField** (K8s data with camelCase keys inside):
+- `Route.rules` - K8s Gateway API (`backendRefs`, `requestRedirect`, etc.)
+- `Config.healthcheck` - K8s probes (`livenessProbe`, `httpGet`, etc.)
+- `Config.lifecycle` - K8s lifecycle (`postStart`, `preStop`, etc.)
+- `AddonInstance.parameters` - user/Helm parameters (may have camelCase keys)
+- `PodDetailSerializer.state`/`last_state` - K8s container state
+- `DeploymentDetailSerializer.liveness_probe`/`readiness_probe`/`volume_mounts`
+
+**When NOT to use CamelCaseJSONField** (single-word keys or non-K8s data):
+- `Gateway.ports` - keys are `port`, `protocol` (single words)
+- `Route.parent_refs` - keys are `name`, `port` (single words)
+- `Config.values` - keys are `name`, `value`, `ptype` (single words)
+- `Config.tags` - K8s labels (dots/hyphens, not camelCase)
+- `AppSettings.autoscale` - already snake_case (`cpu_percent`), HPA code converts
+
 ## URL Conventions
 
 URLs use `re_path` in `api/urls.py`. Workspace-managed resources are **flat** at top-level:
diff --git a/rootfs/api/models/app.py b/rootfs/api/models/app.py
@@ -694,9 +694,9 @@ def get_command_and_args(pod, container_name):
                         "command": command,
                         "args": args,
                         "state": status.get("state", {}),
-                        "lastState": status.get("lastState", {}),
+                        "last_state": status.get("lastState", {}),
                         "ready": status.get("ready", False),
-                        "restartCount": status.get("restartCount", 0),
+                        "restart_count": status.get("restartCount", 0),
                         "status": pod["status"].get("phase", ""),
                         "reason": pod["status"].get("reason", ""),
                         "message": pod["status"].get("message", ""),
diff --git a/rootfs/api/serializers/__init__.py b/rootfs/api/serializers/__init__.py
@@ -131,6 +131,53 @@ def to_representation(self, obj):
         return obj
 
 
+class CamelCaseJSONField(JSONFieldSerializer):
+    """JSONField that stores camelCase data and accepts snake_case input.
+
+    - Input  (API -> DB):  snake_case keys -> camelCase (before validation)
+    - Output (DB -> API):  camelCase keys -> snake_case
+    - Storage: camelCase (Python code & K8s API unchanged)
+    """
+
+    @staticmethod
+    def camel_to_snake(s):
+        """camelCase -> snake_case"""
+        s1 = re.sub(r'(.)([A-Z][a-z]+)', r'\1_\2', s)
+        return re.sub(r'([a-z0-9])([A-Z])', r'\1_\2', s1).lower()
+
+    @staticmethod
+    def snake_to_camel(s):
+        """snake_case -> camelCase"""
+        parts = s.split('_')
+        return parts[0] + ''.join(x.title() for x in parts[1:])
+
+    @classmethod
+    def underscoreize(cls, data):
+        """Recursively convert dict keys: camelCase -> snake_case"""
+        if isinstance(data, dict):
+            return {cls.camel_to_snake(k): cls.underscoreize(v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [cls.underscoreize(i) for i in data]
+        return data
+
+    @classmethod
+    def camelize(cls, data):
+        """Recursively convert dict keys: snake_case -> camelCase"""
+        if isinstance(data, dict):
+            return {cls.snake_to_camel(k): cls.camelize(v) for k, v in data.items()}
+        if isinstance(data, list):
+            return [cls.camelize(i) for i in data]
+        return data
+
+    def to_internal_value(self, data):
+        val = super().to_internal_value(data)
+        return self.camelize(val)
+
+    def to_representation(self, obj):
+        val = super().to_representation(obj)
+        return self.underscoreize(val)
+
+
 class AuthSerializer(serializers.Serializer):
     username = serializers.CharField(
         label=gettext_lazy("Username"),
@@ -283,10 +330,10 @@ class ConfigSerializer(serializers.ModelSerializer):
     app = serializers.SlugRelatedField(slug_field='id', queryset=models.app.App.objects.all())
     values = JSONFieldSerializer(required=False, binary=True)
     limits = JSONFieldSerializer(required=False, binary=True)
-    lifecycle = JSONFieldSerializer(convert_to_str=False, required=False, binary=True)
+    lifecycle = CamelCaseJSONField(convert_to_str=False, required=False, binary=True)
     tags = JSONFieldSerializer(required=False, binary=True)
     registry = JSONFieldSerializer(required=False, binary=True)
-    healthcheck = JSONFieldSerializer(convert_to_str=False, required=False, binary=True)
+    healthcheck = CamelCaseJSONField(convert_to_str=False, required=False, binary=True)
     routable = serializers.BooleanField(required=False)
     termination_grace_period = JSONFieldSerializer(required=False, binary=True)
 
@@ -509,12 +556,15 @@ class ServiceSerializer(serializers.ModelSerializer):
     protocol = serializers.CharField(required=True)
     target_port = serializers.IntegerField(default=DEFAULT_CONTAINER_PORT)
     ptype = serializers.CharField(required=True)
+    name = serializers.ReadOnlyField()
+    domain = serializers.ReadOnlyField()
+    ports = CamelCaseJSONField()
 
     class Meta:
         """Metadata options for a :class:`ServiceSerializer`."""
         model = models.service.Service
-        fields = ['created', 'updated', 'app', 'ptype']
-        read_only_fields = ['uuid']
+        fields = ['created', 'updated', 'app', 'ptype', 'name', 'domain', 'ports']
+        read_only_fields = ['created', 'updated', 'name', 'domain', 'ports']
 
     @staticmethod
     def validate_protocol(value):
@@ -566,6 +616,34 @@ def to_representation(self, obj):
         return obj
 
 
+class PodDetailSerializer(serializers.Serializer):
+    """Serialize pod detail data from Kubernetes API."""
+    container = serializers.CharField()
+    image = serializers.CharField()
+    command = serializers.JSONField()
+    args = serializers.JSONField()
+    state = CamelCaseJSONField()
+    last_state = CamelCaseJSONField()
+    ready = serializers.BooleanField()
+    restart_count = serializers.IntegerField()
+    status = serializers.CharField()
+    reason = serializers.CharField()
+    message = serializers.CharField()
+
+
+class DeploymentDetailSerializer(serializers.Serializer):
+    """Serialize deployment detail data from Kubernetes API."""
+    container = serializers.CharField()
+    image = serializers.CharField()
+    command = serializers.JSONField()
+    args = serializers.JSONField()
+    liveness_probe = CamelCaseJSONField()
+    readiness_probe = CamelCaseJSONField()
+    limits = serializers.JSONField()
+    volume_mounts = CamelCaseJSONField()
+    node_selector = serializers.JSONField()
+
+
 class EventSerializer(serializers.BaseSerializer):
     reason = serializers.CharField()
     message = serializers.CharField()
@@ -626,7 +704,7 @@ class VolumeSerializer(serializers.ModelSerializer):
 
     app = serializers.SlugRelatedField(slug_field='id', queryset=models.app.App.objects.all())
     path = JSONFieldSerializer(required=False, binary=True)
-    parameters = serializers.JSONField(required=False)
+    parameters = CamelCaseJSONField(required=False)
 
     class Meta:
         """Metadata options for a :class:`AppVolumeSerializer`."""
@@ -717,7 +795,7 @@ class GatewaySerializer(serializers.ModelSerializer):
 
     class Meta:
         model = models.gateway.Gateway
-        fields = '__all__'
+        fields = ['app', 'name', 'ports', 'addresses', 'created', 'updated']
 
     validate_name = staticmethod(validate_name)
 
@@ -756,14 +834,14 @@ class RouteSerializer(serializers.ModelSerializer):
     app = serializers.SlugRelatedField(slug_field='id', queryset=models.app.App.objects.all())
     kind = serializers.CharField(max_length=15, required=True)
     name = serializers.CharField(max_length=63, required=True)
-    rules = serializers.JSONField(required=True)
+    rules = CamelCaseJSONField(convert_to_str=False, required=True)
     routable = serializers.BooleanField(read_only=True)
     parent_refs = serializers.JSONField(required=True)
 
     class Meta:
         """Metadata options for a :class:`RouteSerializer`."""
         model = models.gateway.Route
-        fields = '__all__'
+        fields = ['app', 'kind', 'name', 'rules', 'routable', 'parent_refs', 'created', 'updated']
 
     validate_name = staticmethod(validate_name)
 
@@ -843,35 +921,24 @@ class Meta:
         read_only_fields = ['id', 'token', 'created']
 
 
-class AddonClassSerializer(serializers.BaseSerializer):
+class AddonClassSerializer(serializers.Serializer):
     """Serialize AddonClass data from Kubernetes CRD."""
-
-    name = serializers.CharField(required=False)
-    description = serializers.CharField(required=False)
-    kind = serializers.CharField(required=False)
-    storage_model = serializers.CharField(required=False)
-    plans = serializers.ListField(required=False)
-
-    def to_representation(self, instance):
-        spec = instance.get('spec', {})
-        target_resource = spec.get('targetResource', {})
-        return {
-            'name': instance.get('metadata', {}).get('name', ''),
-            'description': spec.get('description', ''),
-            'kind': target_resource.get('kind', ''),
-            'storage_model': spec.get('storageModel', ''),
-            'plans': spec.get('plans', []),
-        }
+    name = serializers.CharField(source='metadata.name', required=False)
+    description = serializers.CharField(source='spec.description', required=False)
+    kind = serializers.CharField(source='spec.targetResource.kind', required=False)
+    storage_model = serializers.CharField(source='spec.storageModel', required=False)
+    plans = CamelCaseJSONField(source='spec.plans', required=False)
 
 
 class AddonInstanceSerializer(serializers.ModelSerializer):
     """Serialize AddonInstance model."""
     app = serializers.ReadOnlyField(source='app.id')
     name = serializers.CharField(max_length=63, required=False)
     kind = serializers.CharField(max_length=63, required=False)
+    parameters = CamelCaseJSONField(convert_to_str=False, default=dict, required=False)
 
     class Meta:
         model = models.addon.AddonInstance
-        fields = ['uuid', 'name', 'app', 'plan', 'kind',
+        fields = ['name', 'app', 'plan', 'kind',
                   'multiplier', 'parameters', 'created', 'updated']
-        read_only_fields = ['uuid', 'multiplier', 'created', 'updated']
+        read_only_fields = ['multiplier', 'created', 'updated']
diff --git a/rootfs/api/tests/test_addon.py b/rootfs/api/tests/test_addon.py
@@ -249,8 +249,8 @@ def test_list_addonclasses(self, mock_gs):
         for plan in response.data['results'][0]['plans']:
             self.assertNotIn('defaults', plan)
             self.assertNotIn('overrides', plan)
-            self.assertIn('allowCreate', plan)
-            self.assertIn('allowUpdate', plan)
+            self.assertIn('allow_create', plan)
+            self.assertIn('allow_update', plan)
 
     @mock.patch('api.views.addon.get_scheduler')
     def test_retrieve_addonclass(self, mock_gs):
@@ -281,7 +281,7 @@ def test_addonclass_visible_paths_fallback(self, mock_gs):
         for plan in response.data['plans']:
             self.assertNotIn('defaults', plan)
             self.assertNotIn('overrides', plan)
-            self.assertIn('allowCreate', plan)
+            self.assertIn('allow_create', plan)
 
     @mock.patch('api.views.addon.get_scheduler')
     def test_addonclass_visible_paths_nested_jsonpath(self, mock_gs):
@@ -299,11 +299,11 @@ def test_addonclass_visible_paths_nested_jsonpath(self, mock_gs):
         self.assertEqual(response.status_code, 200, response.data)
         plan = response.data['plans'][0]
         self.assertEqual(plan['name'], 'micro')
-        self.assertEqual(plan['defaults'], {'imagePullPolicy': 'IfNotPresent'})
+        self.assertEqual(plan['defaults'], {'image_pull_policy': 'IfNotPresent'})
         self.assertNotIn('replicas', plan.get('defaults', {}))
         self.assertNotIn('persistence', plan.get('defaults', {}))
         self.assertNotIn('overrides', plan)
-        self.assertNotIn('allowCreate', plan)
+        self.assertNotIn('allow_create', plan)
 
     @mock.patch('api.views.addon.get_scheduler')
     def test_retrieve_nonexistent_addonclass(self, mock_gs):
diff --git a/rootfs/api/tests/test_gateway.py b/rootfs/api/tests/test_gateway.py
@@ -667,7 +667,7 @@ def test_route_rules_get_returns_backendRefs_for_api(self):
             '/v2/apps/{}/routes/{}/'.format(app_id, route_name),
         )
         expect = [{
-            'backendRefs': [{
+            'backend_refs': [{
                 'kind': 'Service',
                 'name': '%s-%s' % (app_id, ptype),
                 'port': 5000,
@@ -689,7 +689,7 @@ def test_route_rules_set_accepts_backendRefs_for_storage(self):
         app_id = self.create_app()
         ptype, _, route_name = self.create_route(app_id)
         expect = [{
-            "backendRefs": [{
+            "backend_refs": [{
                 "kind": "Service",
                 "name": "%s-%s" % (app_id, ptype),
                 "port": 5000,
@@ -763,7 +763,7 @@ def test_route_serializer_accepts_backendRefs_input(self):
         self.assertEqual(
             response.data["rules"],
             [{
-                "backendRefs": [{
+                "backend_refs": [{
                     "kind": "Service",
                     "name": f"{app_id}-{ptype}",
                     "port": port,
diff --git a/rootfs/api/tests/test_healthchecks.py b/rootfs/api/tests/test_healthchecks.py
@@ -30,31 +30,31 @@ def test_config_healthchecks(self, mock_requests):
         """
         app_id = self.create_app()
         readiness_probe = {
-            'healthcheck': {'web': {'readinessProbe': {'httpGet': {'port': 5000}}}}
+            'healthcheck': {'web': {'readiness_probe': {'http_get': {'port': 5000}}}}
         }
         response = self.client.post(
             f'/v2/apps/{app_id}/config',
             readiness_probe)
         self.assertEqual(response.status_code, 201, response.data)
-        self.assertIn('readinessProbe', response.data['healthcheck']['web'])
+        self.assertIn('readiness_probe', response.data['healthcheck']['web'])
         self.assertEqual(response.data['healthcheck'], readiness_probe['healthcheck'])
 
-        liveness_probe = {'healthcheck': {'web': {'livenessProbe':
-                                          {'httpGet': {'port': 5000},
-                                           'successThreshold': 1}}}}
+        liveness_probe = {'healthcheck': {'web': {'liveness_probe':
+                                          {'http_get': {'port': 5000},
+                                           'success_threshold': 1}}}}
         response = self.client.post(
             f'/v2/apps/{app_id}/config',
             liveness_probe)
         self.assertEqual(response.status_code, 201, response.data)
-        self.assertIn('livenessProbe', response.data['healthcheck']['web'])
+        self.assertIn('liveness_probe', response.data['healthcheck']['web'])
         self.assertEqual(
-            response.data['healthcheck']['web']['livenessProbe'],
-            liveness_probe['healthcheck']['web']['livenessProbe'])
+            response.data['healthcheck']['web']['liveness_probe'],
+            liveness_probe['healthcheck']['web']['liveness_probe'])
         # check that the readiness probe is still there too!
-        self.assertIn('readinessProbe', response.data['healthcheck']['web'])
+        self.assertIn('readiness_probe', response.data['healthcheck']['web'])
         self.assertEqual(
-            response.data['healthcheck']['web']['readinessProbe'],
-            readiness_probe['healthcheck']['web']['readinessProbe'])
+            response.data['healthcheck']['web']['readiness_probe'],
+            readiness_probe['healthcheck']['web']['readiness_probe'])
 
         # check that config fails if trying to unset non-existing healthcheck
         response = self.client.post(
@@ -65,10 +65,10 @@ def test_config_healthchecks(self, mock_requests):
         # remove a probeType
         response = self.client.post(
             f'/v2/apps/{app_id}/config',
-            {'healthcheck': {'web': {'livenessProbe': None}}})
+            {'healthcheck': {'web': {'liveness_probe': None}}})
         self.assertEqual(response.status_code, 201, response.data)
-        self.assertNotIn('livenessProbe', response.data['healthcheck']['web'])
-        self.assertIn('readinessProbe', response.data['healthcheck']['web'])
+        self.assertNotIn('liveness_probe', response.data['healthcheck']['web'])
+        self.assertIn('readiness_probe', response.data['healthcheck']['web'])
 
         # check that config fails if trying to unset non-existing probeType
         response = self.client.post(
diff --git a/rootfs/api/views/pods.py b/rootfs/api/views/pods.py
diff --git a/rootfs/api/views/settings.py b/rootfs/api/views/settings.py
